@djangocfg/ui-tools 2.1.431 → 2.1.433

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

@@ -1,70 +1,155 @@
 'use client'
 
 /**
- * GeocoderControl - Address search with autocomplete
+ * GeocoderControl — the thin map-bound wrapper around `GeocoderInput`.
  *
- * Requires: @maplibre/maplibre-gl-geocoder
- * CSS: @import '@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css'
+ * Renders the autocomplete as an on-map control (a positioned overlay, top-
+ * left by default). On select it flies the camera to the picked coordinate
+ * via `useMapControl().flyTo`, optionally drops a marker, and calls an
+ * optional `onResult`. Biases search to the current map center (`near`).
  *
- * @example
- * ```tsx
- * import { useState } from 'react'
- * import { useControl, Marker } from '@carapis/map'
- * import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
- *
- * const geocoderApi = {
- *   forwardGeocode: async (config) => {
- *     const features = []
- *     const response = await fetch(
- *       `https://nominatim.openstreetmap.org/search?q=${config.query}&format=geojson`
- *     )
- *     const geojson = await response.json()
- *     for (const feature of geojson.features) {
- *       const center = [
- *         feature.bbox[0] + (feature.bbox[2] - feature.bbox[0]) / 2,
- *         feature.bbox[1] + (feature.bbox[3] - feature.bbox[1]) / 2,
- *       ]
- *       features.push({
- *         type: 'Feature',
- *         geometry: { type: 'Point', coordinates: center },
- *         place_name: feature.properties.display_name,
- *         properties: feature.properties,
- *         text: feature.properties.display_name,
- *         center,
- *       })
- *     }
- *     return { features }
- *   },
- * }
- *
- * function GeocoderControl({ position, onResult }) {
- *   const [marker, setMarker] = useState(null)
- *
- *   useControl(
- *     ({ mapLib }) => {
- *       const ctrl = new MaplibreGeocoder(geocoderApi, {
- *         maplibregl: mapLib,
- *         marker: false,
- *       })
- *       ctrl.on('result', (evt) => {
- *         onResult?.(evt)
- *         const { result } = evt
- *         if (result?.center) {
- *           setMarker(
- *             <Marker longitude={result.center[0]} latitude={result.center[1]} />
- *           )
- *         }
- *       })
- *       return ctrl
- *     },
- *     { position }
- *   )
- *
- *   return marker
- * }
- * ```
+ * Must live inside a `<MapProvider>` (i.e. rendered as a child of
+ * `MapContainer`). The `data-map-control` attribute is load-bearing: the
+ * scroll-protection re-lock skips clicks inside it so the input stays usable.
  */
 
-// Re-export for documentation purposes
-// Actual implementation requires user to install @maplibre/maplibre-gl-geocoder
-export { }
+import { useCallback, useState } from 'react'
+
+import { cn } from '@djangocfg/ui-core/lib'
+
+import { useMapControl } from '../hooks/useMapControl'
+import { useMapViewport } from '../hooks/useMapViewport'
+import { GeocoderInput } from './GeocoderInput'
+import { MapMarker } from './MapMarker'
+import { cameraForResult } from '../geocode'
+import type { GeocodeResult, ResolveGeocode } from '../geocode'
+import type { MarkerData } from '../types'
+
+type ControlCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+
+const cornerClass: Record<ControlCorner, string> = {
+  'top-left': 'top-3 left-3',
+  'top-right': 'top-3 right-3',
+  'bottom-left': 'bottom-3 left-3',
+  'bottom-right': 'bottom-3 right-3',
+}
+
+export interface GeocoderControlProps {
+  /** Injectable resolver. Defaults to public Photon (`photonResolve`). */
+  resolve?: ResolveGeocode
+  /** On-map corner for the search box. Default `top-left`. */
+  position?: ControlCorner
+  /** Input placeholder. */
+  placeholder?: string
+  /**
+   * Override the smart zoom. By default the camera fits the result's extent
+   * (`bbox`) when available, else flies to a zoom chosen by the result kind
+   * (country/city/street/house…). Set this to force a fixed fly-to zoom for
+   * every pick instead.
+   */
+  zoom?: number
+  /** Padding (px) around a fitted bounding box. Default 48. */
+  fitPadding?: number
+  /** Cap the zoom when fitting tiny extents (avoid over-zoom). Default 16. */
+  fitMaxZoom?: number
+  /** Drop a pin at the picked location. Default `true`. */
+  marker?: boolean
+  /** Called with the chosen result after the camera flies. */
+  onResult?: (result: GeocodeResult) => void
+  /** Max results. Default 5. */
+  limit?: number
+  /**
+   * Controlled visibility of the search input. When omitted the control is
+   * uncontrolled and the input is always visible (the standalone, always-on
+   * usage). Pass `open` (with `onClose`) to drive it from a toolbar toggle.
+   */
+  open?: boolean
+  /** Called when the input requests to close (Esc / select). Controlled mode. */
+  onClose?: () => void
+  /** Focus the input when it appears. Default `false`. */
+  autoFocus?: boolean
+  className?: string
+}
+
+export function GeocoderControl({
+  resolve,
+  position = 'top-left',
+  placeholder,
+  zoom,
+  fitPadding = 48,
+  fitMaxZoom = 16,
+  marker = true,
+  onResult,
+  limit,
+  open,
+  onClose,
+  autoFocus = false,
+  className,
+}: GeocoderControlProps) {
+  const { flyTo, fitBounds } = useMapControl()
+  const { center } = useMapViewport()
+  const [pin, setPin] = useState<MarkerData | null>(null)
+
+  // Uncontrolled (no `open` prop) → always visible, like the original
+  // always-on control. Controlled → the host (toolbar chip) owns visibility.
+  const isControlled = open !== undefined
+  const inputVisible = isControlled ? open : true
+
+  const handleSelect = useCallback(
+    (result: GeocodeResult) => {
+      // Smart zoom: a fixed `zoom` override wins; otherwise fit the result's
+      // extent (island, street, district frame themselves) and fall back to a
+      // kind-based zoom for point results with no bbox.
+      const cam = cameraForResult(result)
+      if (zoom !== undefined) {
+        flyTo([result.lng, result.lat], zoom)
+      } else if (cam.type === 'fit') {
+        fitBounds(cam.bbox, { padding: fitPadding, maxZoom: fitMaxZoom })
+      } else {
+        flyTo(cam.center, cam.zoom)
+      }
+      if (marker) {
+        setPin({
+          id: `geocoder-${result.id}`,
+          longitude: result.lng,
+          latitude: result.lat,
+          data: { label: result.label },
+        })
+      }
+      onResult?.(result)
+      // Picking a result dismisses the input in controlled (toolbar) mode.
+      onClose?.()
+    },
+    [flyTo, fitBounds, zoom, fitPadding, fitMaxZoom, marker, onResult, onClose],
+  )
+
+  return (
+    <>
+      {inputVisible ? (
+        <div
+          data-map-control
+          className={cn('absolute z-20 w-72 max-w-[calc(100%-1.5rem)]', cornerClass[position], className)}
+          // Esc closes in controlled mode (the input also stops propagation
+          // of its own Escape, but the wrapper catch covers the case where
+          // focus has left the cmdk input).
+          onKeyDown={(e) => {
+            if (e.key === 'Escape' && isControlled) {
+              e.stopPropagation()
+              onClose?.()
+            }
+          }}
+        >
+          <GeocoderInput
+            resolve={resolve}
+            onSelect={handleSelect}
+            placeholder={placeholder}
+            near={{ lng: center[0], lat: center[1] }}
+            limit={limit}
+            autoFocus={autoFocus}
+          />
+        </div>
+      ) : null}
+      {pin ? <MapMarker marker={pin} ariaLabel={String(pin.data?.label ?? 'Result')} /> : null}
+    </>
+  )
+}

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

@@ -0,0 +1,181 @@
+'use client'
+
+/**
+ * GeocoderInput — a self-contained, map-agnostic address/place autocomplete.
+ *
+ * A text field + a results dropdown (primary `label` + muted `secondary`),
+ * with loading / empty states and keyboard nav (↑/↓ move, Enter select, Esc
+ * close). Resolution is INJECTABLE: pass a `resolve` (default = public
+ * Photon) — the component never hard-couples to a backend.
+ *
+ * Built on ui-core's `Command` primitives (cmdk). cmdk's built-in fuzzy
+ * filter is DISABLED (`shouldFilter={false}`) because results already come
+ * pre-ranked from the resolver — we drive selection state manually so it
+ * works as a live remote-search box.
+ *
+ * Usable WITHOUT a map (plain forms). `GeocoderControl` is the thin map-bound
+ * wrapper that flies the camera on select.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { cn } from '@djangocfg/ui-core/lib'
+import {
+  Command,
+  CommandEmpty,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@djangocfg/ui-core/components'
+
+import { useGeocoder } from '../hooks/useGeocoder'
+import type { GeocodeResult, ResolveGeocode } from '../geocode'
+
+export interface GeocoderInputProps {
+  /** Injectable resolver. Defaults to public Photon (`photonResolve`). */
+  resolve?: ResolveGeocode
+  /** Called with the chosen result when the user picks one. */
+  onSelect?: (result: GeocodeResult) => void
+  /** Input placeholder. */
+  placeholder?: string
+  /** Geo-bias — rank results near this point (e.g. the map center). */
+  near?: { lng: number; lat: number }
+  /** Minimum query length before searching. Default 3. */
+  minLength?: number
+  /** Max results. Default 5. */
+  limit?: number
+  /**
+   * Focus the text field on mount (e.g. when revealed by a toolbar toggle).
+   * @default false
+   */
+  autoFocus?: boolean
+  className?: string
+}
+
+export function GeocoderInput({
+  resolve,
+  onSelect,
+  placeholder = 'Search address or place…',
+  near,
+  minLength = 3,
+  limit,
+  autoFocus = false,
+  className,
+}: GeocoderInputProps) {
+  const { query, setQuery, results, loading, error, select } = useGeocoder({
+    resolve,
+    near,
+    minLength,
+    limit,
+  })
+
+  // Show the dropdown only while focused with a meaningful query.
+  const [open, setOpen] = useState(false)
+
+  // Optional autofocus when revealed (e.g. by the toolbar search chip).
+  // cmdk's `CommandInput` doesn't forward a ref reliably across versions, so
+  // query the rendered `[cmdk-input]` element from the Command root instead.
+  const rootRef = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    if (!autoFocus) return
+    const input = rootRef.current?.querySelector<HTMLInputElement>('[cmdk-input]')
+    input?.focus()
+  }, [autoFocus])
+
+  const handleSelect = useCallback(
+    (result: GeocodeResult) => {
+      onSelect?.(select(result))
+      setOpen(false)
+    },
+    [onSelect, select],
+  )
+
+  const showList = open && query.trim().length >= minLength
+
+  return (
+    // The Command wrapper is a TRANSPARENT positioning context only — the
+    // popover chrome (bg/border/shadow) lives on the input and on the
+    // floating list separately, so nothing peeks out beneath the input when
+    // the list is closed.
+    <Command
+      ref={rootRef}
+      shouldFilter={false}
+      // Esc closes the dropdown without clearing; cmdk handles ↑/↓/Enter.
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') {
+          e.preventDefault()
+          setOpen(false)
+        }
+      }}
+      className={cn(
+        'relative overflow-visible bg-transparent',
+        // Turn cmdk's input WRAPPER into the search field itself: a rounded
+        // popover surface with its own border (drop cmdk's default bottom
+        // border so no line/stub shows beneath the input when closed).
+        '[&_[cmdk-input-wrapper]]:h-10 [&_[cmdk-input-wrapper]]:rounded-lg',
+        '[&_[cmdk-input-wrapper]]:border [&_[cmdk-input-wrapper]]:border-border',
+        '[&_[cmdk-input-wrapper]]:bg-popover [&_[cmdk-input-wrapper]]:text-popover-foreground',
+        '[&_[cmdk-input-wrapper]]:shadow-sm',
+        className,
+      )}
+    >
+      <CommandInput
+        value={query}
+        onValueChange={(v) => {
+          setQuery(v)
+          setOpen(true)
+        }}
+        onFocus={() => setOpen(true)}
+        onBlur={() => {
+          // Delay so an item click registers before the list unmounts.
+          window.setTimeout(() => setOpen(false), 120)
+        }}
+        placeholder={placeholder}
+        aria-label={placeholder}
+      />
+
+      {showList ? (
+        // Floating result panel — its OWN popover surface, anchored under the
+        // input, shown only when there's a query (never an empty stub).
+        <CommandList className="absolute inset-x-0 top-full z-10 mt-1.5 max-h-72 overflow-y-auto rounded-lg border border-border bg-popover text-popover-foreground shadow-md">
+          {loading ? (
+            <div
+              className="px-3 py-6 text-center text-sm text-muted-foreground"
+              aria-busy="true"
+            >
+              Searching…
+            </div>
+          ) : error ? (
+            <div className="px-3 py-6 text-center text-sm text-destructive">
+              Search failed. Try again.
+            </div>
+          ) : (
+            <>
+              <CommandEmpty className="py-6 text-center text-sm text-muted-foreground">
+                No results.
+              </CommandEmpty>
+              {results.map((result) => (
+                <CommandItem
+                  key={result.id}
+                  // cmdk matches `value`; keep it unique + searchable-ish.
+                  value={`${result.id} ${result.label}`}
+                  onSelect={() => handleSelect(result)}
+                  className="flex-col items-start gap-0.5"
+                >
+                  <span className="truncate font-medium text-foreground">
+                    {result.label}
+                  </span>
+                  {result.secondary ? (
+                    <span className="truncate text-xs text-muted-foreground">
+                      {result.secondary}
+                    </span>
+                  ) : null}
+                </CommandItem>
+              ))}
+            </>
+          )}
+        </CommandList>
+      ) : null}
+    </Command>
+  )
+}

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

@@ -0,0 +1,140 @@
+'use client'
+
+import type { ComponentType, ReactNode } from 'react'
+import {
+  Dialog,
+  DialogContent,
+  DialogTitle,
+} from '@djangocfg/ui-core/components'
+
+import type { MapViewport, MapStyleKey } from '../../types'
+import type { GeocodeResult, ResolveGeocode } from '../../geocode'
+import type { MapContainerProps, GeolocateOptions, GeolocatePosition } from './types'
+
+/**
+ * Fullscreen dialog — a fresh map seeded with the current viewport.
+ *
+ * The nested map is the public `MapContainer`, passed in as a prop so this
+ * module never imports the folder index (which would form a cycle:
+ * index → MapInner → FullscreenDialog → index).
+ */
+export function FullscreenDialog({
+  MapContainer,
+  open,
+  onOpenChange,
+  fullscreenTitle,
+  viewport,
+  effectiveStyle,
+  interactiveLayerIds,
+  openInMapsUrl,
+  openInMapsLabel,
+  googleMapsButton,
+  basemapSwitcher,
+  basemaps,
+  onBasemapChange,
+  terrainOn,
+  terrainButton,
+  terrainLabel,
+  onTerrainChange,
+  compassButton,
+  compassLabel,
+  geolocate,
+  geolocateLabel,
+  geolocateOptions,
+  onGeolocate,
+  onGeolocateError,
+  geocoder,
+  geocoderResolve,
+  geocoderPlaceholder,
+  onGeocoderResult,
+  showResetButton,
+  ariaLabel,
+  onClose,
+  children,
+}: {
+  MapContainer: ComponentType<MapContainerProps>
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  fullscreenTitle: string
+  viewport: MapViewport
+  effectiveStyle: MapStyleKey | string
+  interactiveLayerIds: string[] | undefined
+  openInMapsUrl: string | undefined
+  openInMapsLabel: string
+  googleMapsButton: boolean
+  basemapSwitcher: boolean
+  basemaps: MapStyleKey[] | undefined
+  onBasemapChange: ((key: MapStyleKey) => void) | undefined
+  terrainOn: boolean
+  terrainButton: boolean
+  terrainLabel: string
+  onTerrainChange: ((enabled: boolean) => void) | undefined
+  compassButton: boolean
+  compassLabel: string
+  geolocate: boolean
+  geolocateLabel: string
+  geolocateOptions: GeolocateOptions | undefined
+  onGeolocate: ((pos: GeolocatePosition) => void) | undefined
+  onGeolocateError: ((err: GeolocationPositionError) => void) | undefined
+  geocoder: boolean
+  geocoderResolve: ResolveGeocode | undefined
+  geocoderPlaceholder: string | undefined
+  onGeocoderResult: ((result: GeocodeResult) => void) | undefined
+  showResetButton: boolean
+  ariaLabel: string
+  onClose: () => void
+  children?: ReactNode
+}) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        className="h-[90vh] w-[90vw] max-w-[1400px] overflow-hidden p-0 sm:rounded-xl"
+        // The dialog's own X is suppressed — the map renders close as the
+        // first chip in its top-right toolbar (via `onClose`), so close /
+        // Google / reset share one tidy column like the inline map.
+        closeButton={false}
+      >
+        <DialogTitle className="sr-only">{fullscreenTitle}</DialogTitle>
+        {open && (
+          <MapContainer
+            initialViewport={viewport}
+            // Carry the user's current basemap choice into fullscreen.
+            mapStyle={effectiveStyle}
+            interactiveLayerIds={interactiveLayerIds}
+            attributionControl={false}
+            reuseMaps={false}
+            openInMapsUrl={openInMapsUrl}
+            openInMapsLabel={openInMapsLabel}
+            googleMapsButton={googleMapsButton}
+            basemapSwitcher={basemapSwitcher}
+            basemaps={basemaps}
+            onBasemapChange={onBasemapChange}
+            terrain={terrainOn}
+            terrainButton={terrainButton}
+            terrainLabel={terrainLabel}
+            onTerrainChange={onTerrainChange}
+            compassButton={compassButton}
+            compassLabel={compassLabel}
+            geolocate={geolocate}
+            geolocateLabel={geolocateLabel}
+            geolocateOptions={geolocateOptions}
+            onGeolocate={onGeolocate}
+            onGeolocateError={onGeolocateError}
+            geocoder={geocoder}
+            geocoderResolve={geocoderResolve}
+            geocoderPlaceholder={geocoderPlaceholder}
+            onGeocoderResult={onGeocoderResult}
+            showResetButton={showResetButton}
+            ariaLabel={ariaLabel}
+            scrollProtection={false}
+            fullscreenButton={false}
+            onClose={onClose}
+            className="h-full w-full"
+          >
+            {children}
+          </MapContainer>
+        )}
+      </DialogContent>
+    </Dialog>
+  )
+}

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

@@ -0,0 +1,70 @@
+'use client'
+
+import { forwardRef } from 'react'
+import {
+  GeolocateControl,
+  type GeolocateControlInstance,
+  type GeolocateResultEvent,
+  type GeolocateErrorEvent,
+} from 'react-map-gl/maplibre'
+
+import type { GeolocateOptions, GeolocatePosition } from './types'
+
+/** The follow-state our chip reflects, derived from the control's events. */
+export type GeolocateState = 'idle' | 'active' | 'error'
+
+interface GeolocateHandleProps {
+  options: GeolocateOptions
+  onGeolocate?: (pos: GeolocatePosition) => void
+  onGeolocateError?: (err: GeolocationPositionError) => void
+  onStateChange: (state: GeolocateState) => void
+}
+
+/**
+ * The maplibre `GeolocateControl`, rendered as a child of `<Map>` so its
+ * location dot + accuracy circle draw on the map, but with the default
+ * control button **hidden** (`display:none`) — our `MapToolbar` chip is the
+ * UI and drives it via the forwarded instance ref (`control.trigger()`).
+ *
+ * `trackUserLocation` gives Google-style follow: first activation centers +
+ * follows; panning away drops to passive; re-trigger re-follows. We reflect
+ * active/error back to the chip through `onStateChange`.
+ *
+ * Note: maplibre-gl 4.7.1's `GeolocateControlOptions` has no `showUserHeading`
+ * field, so heading is surfaced via `onGeolocate` (and `showHeading` is a
+ * forward-compatible no-op on this version).
+ */
+export const GeolocateHandle = forwardRef<GeolocateControlInstance, GeolocateHandleProps>(
+  function GeolocateHandle({ options, onGeolocate, onGeolocateError, onStateChange }, ref) {
+    return (
+      <GeolocateControl
+        ref={ref}
+        // Hidden: our chip is the UI. The dot + accuracy circle are map
+        // layers (not this button), so they still render.
+        style={{ display: 'none' }}
+        trackUserLocation
+        showUserLocation
+        showAccuracyCircle={options.showAccuracyCircle ?? true}
+        positionOptions={{ enableHighAccuracy: options.highAccuracy ?? false }}
+        fitBoundsOptions={
+          options.fitBoundsMaxZoom != null ? { maxZoom: options.fitBoundsMaxZoom } : undefined
+        }
+        onGeolocate={(e: GeolocateResultEvent) => {
+          const c = e.coords
+          onGeolocate?.({
+            lat: c.latitude,
+            lng: c.longitude,
+            accuracy: c.accuracy,
+            heading: c.heading != null && !Number.isNaN(c.heading) ? c.heading : null,
+          })
+        }}
+        onError={(e: GeolocateErrorEvent) => {
+          onStateChange('error')
+          onGeolocateError?.(e)
+        }}
+        onTrackUserLocationStart={() => onStateChange('active')}
+        onTrackUserLocationEnd={() => onStateChange('idle')}
+      />
+    )
+  },
+)