@djangocfg/ui-tools 2.1.431 → 2.1.432

package/src/tools/dev/Map/components/MapContainer/constants.ts

@@ -0,0 +1,15 @@
+import { cn } from '@djangocfg/ui-core/lib'
+
+/**
+ * Controls overlaid on the map. The map tiles are always a light basemap,
+ * but per ui-core's style guide we use semantic tokens (never raw color
+ * scales). `popover` is the floating-chrome surface — the same token
+ * tooltips/menus use — so these chips read like maplibre's own controls
+ * and stay legible over the map in both light and dark themes.
+ */
+export 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'
+)

package/src/tools/dev/Map/components/MapContainer/hooks/useAutoReset.ts

@@ -0,0 +1,51 @@
+'use client'
+
+import { useCallback, useEffect, useRef } from 'react'
+
+/**
+ * Auto-reset timer. After `autoResetDelay` ms of inactivity the map eases back
+ * to its initial viewport. Interaction (move-start) cancels any pending reset;
+ * move-end (re)arms the timer when the feature is enabled.
+ */
+export function useAutoReset({
+  autoResetDelay,
+  resetToInitial,
+}: {
+  autoResetDelay: number
+  resetToInitial: () => void
+}) {
+  const resetTimerRef = useRef<NodeJS.Timeout | null>(null)
+  const isInteractingRef = useRef(false)
+
+  const handleMoveStart = useCallback(() => {
+    isInteractingRef.current = true
+    // Clear any pending reset timer
+    if (resetTimerRef.current) {
+      clearTimeout(resetTimerRef.current)
+      resetTimerRef.current = null
+    }
+  }, [])
+
+  const handleMoveEnd = useCallback(() => {
+    isInteractingRef.current = false
+    // Start auto-reset timer if enabled
+    if (autoResetDelay > 0) {
+      resetTimerRef.current = setTimeout(() => {
+        if (!isInteractingRef.current) {
+          resetToInitial()
+        }
+      }, autoResetDelay)
+    }
+  }, [autoResetDelay, resetToInitial])
+
+  // Cleanup timer on unmount
+  useEffect(() => {
+    return () => {
+      if (resetTimerRef.current) {
+        clearTimeout(resetTimerRef.current)
+      }
+    }
+  }, [])
+
+  return { handleMoveStart, handleMoveEnd }
+}

package/src/tools/dev/Map/components/MapContainer/hooks/useBasemapState.ts

@@ -0,0 +1,48 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+import { MAP_STYLES, resolveBasemapOptions } from '../../../styles'
+import type { MapStyleKey } from '../../../types'
+
+/**
+ * Active basemap state. Seeded from `mapStyle`, then driven by the switcher.
+ * If `mapStyle` is a built-in KEY we track it as the active key; a raw URL is
+ * kept as-is (the switcher still works, just starts "unselected").
+ */
+export function useBasemapState({
+  mapStyle,
+  basemaps,
+  onBasemapChange,
+}: {
+  mapStyle: MapStyleKey | string
+  basemaps: MapStyleKey[] | undefined
+  onBasemapChange: ((key: MapStyleKey) => void) | undefined
+}) {
+  const initialKey = (mapStyle in MAP_STYLES ? mapStyle : undefined) as MapStyleKey | undefined
+  const [activeKey, setActiveKey] = useState<MapStyleKey | undefined>(initialKey)
+  // Follow controlled `mapStyle` changes from the host.
+  useEffect(() => {
+    setActiveKey(mapStyle in MAP_STYLES ? (mapStyle as MapStyleKey) : undefined)
+  }, [mapStyle])
+  // The style actually rendered: the chosen key's URL, else the raw prop.
+  const effectiveStyle = activeKey ?? mapStyle
+  const basemapOptions = useMemo(
+    () => resolveBasemapOptions(basemaps, activeKey ?? (mapStyle as MapStyleKey | string)),
+    [basemaps, activeKey, mapStyle],
+  )
+  const handleBasemapPick = useCallback(
+    (key: string) => {
+      setActiveKey(key as MapStyleKey)
+      onBasemapChange?.(key as MapStyleKey)
+    },
+    [onBasemapChange],
+  )
+
+  // Resolve the EFFECTIVE style (switcher-aware) to a URL/object.
+  const resolvedStyle = effectiveStyle in MAP_STYLES
+    ? MAP_STYLES[effectiveStyle as MapStyleKey]
+    : effectiveStyle
+
+  return { activeKey, effectiveStyle, resolvedStyle, basemapOptions, handleBasemapPick }
+}

package/src/tools/dev/Map/components/MapContainer/hooks/useExternalMapsUrl.ts

@@ -0,0 +1,29 @@
+'use client'
+
+import type { MapViewport } from '../../../types'
+
+/**
+ * External-maps link. A host-supplied `openInMapsUrl` wins (Apple Maps, a
+ * custom deep link); otherwise deep-link to Google Maps at the current center
+ * so the button always works without configuration.
+ */
+export function useExternalMapsUrl({
+  openInMapsUrl,
+  openInMapsLabel,
+  googleMapsButton,
+  viewport,
+}: {
+  openInMapsUrl: string | undefined
+  openInMapsLabel: string
+  googleMapsButton: boolean
+  viewport: MapViewport
+}) {
+  const externalMapsUrl =
+    openInMapsUrl ??
+    (googleMapsButton
+      ? `https://www.google.com/maps/search/?api=1&query=${viewport.latitude},${viewport.longitude}`
+      : undefined)
+  const externalMapsLabel = openInMapsUrl ? openInMapsLabel : 'Open in Google Maps'
+
+  return { externalMapsUrl, externalMapsLabel }
+}

package/src/tools/dev/Map/components/MapContainer/index.tsx

@@ -0,0 +1,29 @@
+'use client'
+
+import { MapProvider } from '../../context'
+import { MapInner } from './MapInner'
+import type { MapContainerProps } from './types'
+
+export type { MapContainerProps, GeolocateOptions, GeolocatePosition } from './types'
+
+export function MapContainer({
+  children,
+  initialViewport,
+  className,
+  ...props
+}: MapContainerProps) {
+  return (
+    <div className={className} style={{ width: '100%', height: '100%', position: 'relative' }}>
+      <MapProvider initialViewport={initialViewport}>
+        <MapInner {...props} MapContainerComponent={MapContainer}>{children}</MapInner>
+      </MapProvider>
+    </div>
+  )
+}
+
+/**
+ * Use this when you need the map inside an existing MapProvider
+ */
+export function MapView(props: Omit<MapContainerProps, 'initialViewport'>) {
+  return <MapInner {...props} MapContainerComponent={MapContainer} />
+}

package/src/tools/dev/Map/components/MapContainer/types.ts

@@ -0,0 +1,198 @@
+import type { ReactNode } from 'react'
+
+import type { MapViewport, MapStyleKey } from '../../types'
+import type { GeocodeResult, ResolveGeocode } from '../../geocode'
+
+/**
+ * Tunables forwarded to the maplibre `GeolocateControl` that backs the
+ * locate-me chip. All optional; sensible privacy-friendly defaults.
+ */
+export interface GeolocateOptions {
+  /**
+   * Use the device's high-accuracy provider (GPS). More precise but slower
+   * and battery-hungry — off by default.
+   * @default false
+   */
+  highAccuracy?: boolean
+  /**
+   * Show a heading arrow on the location dot when a compass heading is
+   * available. (No-op on maplibre versions without heading support.)
+   * @default true
+   */
+  showHeading?: boolean
+  /**
+   * Draw the translucent accuracy circle (95% confidence) around the dot.
+   * @default true
+   */
+  showAccuracyCircle?: boolean
+  /**
+   * Cap how far the camera zooms in when easing to the user (very accurate
+   * fixes can otherwise zoom street-level).
+   */
+  fitBoundsMaxZoom?: number
+}
+
+/** A single successful position fix surfaced to `onGeolocate`. */
+export interface GeolocatePosition {
+  lat: number
+  lng: number
+  /** Accuracy radius in meters. */
+  accuracy: number
+  /** Compass heading in degrees (0 = north), or null when unknown. */
+  heading: number | null
+}
+
+export interface MapContainerProps {
+  children?: ReactNode
+  initialViewport?: Partial<MapViewport>
+  mapStyle?: MapStyleKey | string
+  interactiveLayerIds?: string[]
+  className?: string
+  style?: React.CSSProperties
+  cursor?: string
+  /**
+   * Show the CARTO / OpenStreetMap attribution pill. Off by default for a
+   * clean embedded look. Note: CARTO & OSM licenses require attribution to
+   * appear somewhere — if you hide it here, surface it elsewhere in your UI.
+   * @default false
+   */
+  attributionControl?: boolean
+  /**
+   * Pool and reuse maplibre instances across mounts. Off by default — a
+   * reused instance can come back style-less (blank map) under Storybook
+   * HMR / story switches / chat lists. Enable only for a single, stable,
+   * long-lived full-page map.
+   * @default false
+   */
+  reuseMaps?: boolean
+  /**
+   * URL to open in an external maps app. When omitted, a Google Maps URL
+   * is generated from the current center (see `googleMapsButton`). Pass
+   * this to point at Apple Maps / a custom deep link instead.
+   */
+  openInMapsUrl?: string
+  /** Label for the open in maps button */
+  openInMapsLabel?: string
+  /**
+   * Show an "Open in Google Maps" button that deep-links to the current
+   * center. Suppressed when `openInMapsUrl` is provided (the host link
+   * takes over). Set `false` to hide it.
+   * @default true
+   */
+  googleMapsButton?: boolean
+  /** Auto-reset to initial viewport after N ms of inactivity (0 = disabled) */
+  autoResetDelay?: number
+  /** Show reset button */
+  showResetButton?: boolean
+  /**
+   * Block wheel/trackpad zoom until the user clicks the map (Google Maps
+   * style). Stops an inline map from hijacking the page scroll. Drag-pan,
+   * touch and double-click zoom stay live. Click outside or move the
+   * pointer off the map to re-lock.
+   * @default true
+   */
+  scrollProtection?: boolean
+  /** Hint shown on the lock overlay while scroll-zoom is blocked. */
+  scrollProtectionHint?: string
+  /**
+   * Show a button that opens the map full-screen in a large dialog
+   * (Google-Maps-style "expand"). Scroll protection is off inside the
+   * dialog since the map already fills the screen.
+   * @default true
+   */
+  fullscreenButton?: boolean
+  /** Accessible / tooltip label for the fullscreen button. */
+  fullscreenLabel?: string
+  /** Title for the fullscreen dialog (screen readers). */
+  fullscreenTitle?: string
+  /**
+   * Show a basemap switcher (a Layers button → dropdown) in the toolbar,
+   * Google-Maps style. Lets the user pick the map style at runtime.
+   * @default true
+   */
+  basemapSwitcher?: boolean
+  /**
+   * Explicit list of basemap keys to offer in the switcher. When omitted,
+   * the switcher shows all key-free built-ins (CARTO + OpenFreeMap) plus
+   * `satellite` only if it's actually usable (host-keyed). See
+   * `resolveBasemapOptions`.
+   */
+  basemaps?: MapStyleKey[]
+  /** Accessible / tooltip label for the basemap switcher button. */
+  basemapLabel?: string
+  /** Notified when the user picks a basemap from the switcher. */
+  onBasemapChange?: (key: MapStyleKey) => void
+  /**
+   * Render 3D terrain + hillshade from the free AWS Terrarium DEM (no API
+   * key). Eases the camera pitch in so it reads as 3D; toggles off cleanly.
+   * @default false
+   */
+  terrain?: boolean
+  /**
+   * Show a toolbar chip (a Mountain icon) that toggles 3D terrain at
+   * runtime, in the same top-right control column as the other chips.
+   * @default true
+   */
+  terrainButton?: boolean
+  /** Accessible / tooltip label for the terrain toggle button. */
+  terrainLabel?: string
+  /** Notified when the user toggles terrain from the chip. */
+  onTerrainChange?: (enabled: boolean) => void
+  /**
+   * Show a compass chip that appears only when the map is rotated or
+   * tilted (Google-style); its needle reflects the current bearing and a
+   * click eases the camera back to a north-up, top-down view. Rotate/tilt
+   * the map with right-drag, Ctrl+drag, or two fingers.
+   * @default true
+   */
+  compassButton?: boolean
+  /** Accessible / tooltip label for the compass (reset-north) button. */
+  compassLabel?: string
+  /**
+   * Show a Google-style "locate me" chip that drives maplibre's built-in
+   * `GeolocateControl` — centers + follows the user (track mode), with a
+   * location dot + accuracy circle. Privacy: **off by default**; nothing
+   * requests the OS permission prompt unless this is `true` AND the user
+   * presses the chip. Requires a secure context (HTTPS / localhost).
+   * @default false
+   */
+  geolocate?: boolean
+  /** Accessible / tooltip label for the locate-me chip. */
+  geolocateLabel?: string
+  /** Tunables forwarded to the underlying `GeolocateControl`. */
+  geolocateOptions?: GeolocateOptions
+  /** Notified on each successful position fix while geolocation is active. */
+  onGeolocate?: (pos: GeolocatePosition) => void
+  /** Notified when geolocation fails (permission denied / unavailable / timeout). */
+  onGeolocateError?: (err: GeolocationPositionError) => void
+  /**
+   * Show a Google-Maps-style search chip (a magnifier) in the toolbar that
+   * toggles an on-map address/place autocomplete. Collapsed by default:
+   * clicking the chip reveals an autofocused input (top-left), and clicking
+   * it again / pressing Esc / picking a result hides it. Picking a result
+   * flies the camera there and drops a pin. **Off by default** (opt-in).
+   * @default false
+   */
+  geocoder?: boolean
+  /**
+   * Injectable geocode resolver for the search chip. Defaults to the
+   * free, key-free public Photon endpoint. Pass a backend/route proxy in
+   * production to dodge CORS + throttling.
+   */
+  geocoderResolve?: ResolveGeocode
+  /** Placeholder for the search input. */
+  geocoderPlaceholder?: string
+  /** Notified with the chosen result after the camera flies to it. */
+  onGeocoderResult?: (result: GeocodeResult) => void
+  /**
+   * When set, a close button is rendered as the FIRST chip in the
+   * top-right control toolbar (used by the fullscreen dialog so the
+   * close / Google / reset controls share one tidy column instead of
+   * scattering the dialog's own X into a different corner).
+   */
+  onClose?: () => void
+  /** Accessible label for the map region (screen readers) */
+  ariaLabel?: string
+}
+
+export interface MapInnerProps extends Omit<MapContainerProps, 'initialViewport'> {}

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

@@ -7,13 +7,30 @@ import {
   ScaleControl,
 } from 'react-map-gl/maplibre'
 
+import type { FitBoundsOptions } from 'maplibre-gl'
+
 type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
 
 export interface MapControlsProps {
   position?: ControlPosition
   showNavigation?: boolean
   showFullscreen?: boolean
+  /** Show maplibre's raw `GeolocateControl` (track mode). @default false */
   showGeolocate?: boolean
+  /**
+   * Draw a heading arrow on the location dot. Forwarded to the control; a
+   * no-op on maplibre versions without heading support.
+   */
+  showUserHeading?: boolean
+  /**
+   * Draw the translucent accuracy circle around the dot.
+   * @default true (maplibre default)
+   */
+  showAccuracyCircle?: boolean
+  /** Browser Geolocation API `PositionOptions` (enableHighAccuracy, timeout…). */
+  positionOptions?: PositionOptions
+  /** Options used when the control eases the camera to the user's location. */
+  fitBoundsOptions?: FitBoundsOptions
   showScale?: boolean
   scaleUnit?: 'imperial' | 'metric' | 'nautical'
 }
@@ -23,6 +40,10 @@ export function MapControls({
   showNavigation = true,
   showFullscreen = false,
   showGeolocate = false,
+  showUserHeading,
+  showAccuracyCircle,
+  positionOptions,
+  fitBoundsOptions,
   showScale = false,
   scaleUnit = 'metric',
 }: MapControlsProps) {
@@ -36,6 +57,12 @@ export function MapControls({
         <GeolocateControl
           position={position}
           trackUserLocation
+          // All optional — undefined falls back to maplibre's own defaults,
+          // so existing `showGeolocate` callers are unaffected.
+          {...(showUserHeading !== undefined ? { showUserHeading } : {})}
+          {...(showAccuracyCircle !== undefined ? { showAccuracyCircle } : {})}
+          {...(positionOptions !== undefined ? { positionOptions } : {})}
+          {...(fitBoundsOptions !== undefined ? { fitBoundsOptions } : {})}
         />
       )}
       {showScale && <ScaleControl unit={scaleUnit} />}

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

@@ -0,0 +1,94 @@
+'use client'
+
+import { memo, useCallback, type ReactNode } from 'react'
+import { MapMarker } from './MapMarker'
+import { MapPopup, type MapPopupProps } from './MapPopup'
+import { MarkerCard } from './MarkerCard'
+import { useMarkerCard } from '../hooks/useMarkerCard'
+import type { MarkerData } from '../types'
+import type { MarkerCard as MarkerCardType } from '../cards/types'
+
+/** A marker plus its optional info-card data. */
+export type MarkerWithCard = MarkerData & { card?: MarkerCardType }
+
+export interface MapMarkersProps {
+  /** Markers to render; any with a `card` (or when `renderCard` is set) opens a popup on click. */
+  markers: MarkerWithCard[]
+  /**
+   * Custom card content. When provided it overrides the default `MarkerCard`
+   * for the open marker. `close` dismisses the popup.
+   */
+  renderCard?: (marker: MarkerWithCard, close: () => void) => ReactNode
+  /** Popup anchor — default `'bottom'` so the card sits ABOVE the pin. */
+  cardAnchor?: MapPopupProps['anchor']
+  /** Notified on every marker click (in addition to opening its card). */
+  onMarkerClick?: (marker: MarkerWithCard) => void
+  /** Default-pin color (ignored when a marker supplies `children`-style icon — N/A here). */
+  color?: string
+  /** Default-pin size in px. */
+  size?: number
+}
+
+/**
+ * MapMarkers — the "just works" marker layer. Renders one `MapMarker` per
+ * entry and, on click, opens a `MapPopup` ANCHORED ABOVE the pin showing the
+ * marker's `card` (default `MarkerCard`) or `renderCard` output. Selection is
+ * driven by `useMarkerCard`, so only ONE card is open at a time and clicking
+ * the same pin toggles it. Outside-click / Esc / the popup close button all
+ * dismiss. Must live inside a `<MapProvider>` (a child of MapContainer/MapView,
+ * like `MapLegend`).
+ */
+export const MapMarkers = memo(function MapMarkers({
+  markers,
+  renderCard,
+  cardAnchor = 'bottom',
+  onMarkerClick,
+  color,
+  size,
+}: MapMarkersProps) {
+  const { openId, toggle, close } = useMarkerCard()
+
+  const handleClick = useCallback(
+    (marker: MarkerData) => {
+      toggle(marker.id)
+      onMarkerClick?.(marker as MarkerWithCard)
+    },
+    [toggle, onMarkerClick]
+  )
+
+  const openMarker = openId ? markers.find((m) => m.id === openId) : undefined
+  const hasCard = openMarker && (Boolean(openMarker.card) || Boolean(renderCard))
+
+  return (
+    <>
+      {markers.map((marker) => (
+        <MapMarker
+          key={marker.id}
+          marker={marker}
+          onClick={handleClick}
+          color={color}
+          size={size}
+          ariaLabel={
+            (marker.card?.title as string | undefined) ??
+            (marker.data?.label as string | undefined) ??
+            `Map marker ${marker.id}`
+          }
+        />
+      ))}
+
+      {openMarker && hasCard && (
+        <MapPopup
+          longitude={openMarker.longitude}
+          latitude={openMarker.latitude}
+          anchor={cardAnchor}
+          onClose={close}
+          maxWidth="none"
+        >
+          {renderCard
+            ? renderCard(openMarker, close)
+            : openMarker.card && <MarkerCard {...openMarker.card} />}
+        </MapPopup>
+      )}
+    </>
+  )
+})

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

@@ -0,0 +1,102 @@
+'use client'
+
+import { memo } from 'react'
+import { Button, ButtonLink } from '@djangocfg/ui-core/components'
+import { cn } from '@djangocfg/ui-core/lib'
+import type { MarkerCard as MarkerCardData, MarkerCardAction } from '../cards/types'
+
+export interface MarkerCardProps extends MarkerCardData {
+  /** Extra classes on the card root. */
+  className?: string
+}
+
+const VARIANT_MAP = {
+  default: 'default',
+  outline: 'outline',
+  ghost: 'ghost',
+} as const
+
+function CardAction({ action }: { action: MarkerCardAction }) {
+  const variant = VARIANT_MAP[action.variant ?? 'outline']
+
+  if (action.href) {
+    return (
+      <ButtonLink
+        href={action.href}
+        size="sm"
+        variant={variant}
+        elevated={false}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {action.icon}
+        {action.label}
+      </ButtonLink>
+    )
+  }
+
+  return (
+    <Button size="sm" variant={variant} elevated={false} onClick={action.onClick}>
+      {action.icon}
+      {action.label}
+    </Button>
+  )
+}
+
+/**
+ * MarkerCard — the DEFAULT presentational info-card for a map marker
+ * (Google-Maps-desktop style). Renders from plain data: an optional image
+ * header, a badge pill, a title, a clamped description, and an action row of
+ * links/buttons. Standalone-usable (no map dependency) and built on semantic
+ * tokens only. `MapMarkers` renders this inside a `MapPopup` above the pin.
+ */
+export const MarkerCard = memo(function MarkerCard({
+  title,
+  description,
+  image,
+  badge,
+  actions,
+  className,
+}: MarkerCardProps) {
+  return (
+    <div
+      className={cn(
+        'flex max-w-[260px] flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-md',
+        className
+      )}
+    >
+      {image && (
+        <img
+          src={image}
+          alt={title}
+          className="h-28 w-full object-cover"
+          loading="lazy"
+        />
+      )}
+
+      <div className="flex flex-col gap-1.5 p-3">
+        {badge && (
+          <span className="inline-flex w-fit items-center rounded-full bg-muted px-2 py-0.5 text-[11px] font-medium text-muted-foreground">
+            {badge}
+          </span>
+        )}
+
+        <h3 className="text-sm font-medium leading-snug text-foreground">{title}</h3>
+
+        {description && (
+          <p className="line-clamp-3 text-xs leading-relaxed text-muted-foreground">
+            {description}
+          </p>
+        )}
+
+        {actions && actions.length > 0 && (
+          <div className="mt-1.5 flex flex-wrap gap-1.5">
+            {actions.map((action, i) => (
+              <CardAction key={`${action.label}-${i}`} action={action} />
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+})