@djangocfg/ui-tools 2.1.431 → 2.1.433

package/src/tools/dev/Map/README.md

@@ -1,16 +1,16 @@
 # Map
 
-Interactive maps for `@djangocfg/ui-tools`, built on [MapLibre GL](https://maplibre.org/) via `react-map-gl`. Ships markers, clustered GeoJSON, popups, drawing/geocoder hooks, layer switching, and helpers for overlapping points — all behind a small Provider/Context surface so nothing leaks the raw `Map` instance unless you ask for it.
+Interactive maps for `@djangocfg/ui-tools`, built on [MapLibre GL](https://maplibre.org/) via `react-map-gl` — markers, clustered GeoJSON, popups, layer factories, free OpenFreeMap / PMTiles basemaps, a runtime basemap switcher, 3D terrain, address/place autocomplete (geocoder), a compass, click-to-measure, draggable markers, custom marker icons, and an opt-in locate-me (GPS) chip, all behind a small Provider/Context surface.
 
-> **Bundle warning.** MapLibre GL is heavy (~800 KB gzipped). Prefer `LazyMapContainer` from `./lazy` unless the map is above the fold. All components are `'use client'` — never render them on the Next.js server.
+> **Bundle warning.** MapLibre GL is heavy (~800 KB gzipped). The `@djangocfg/ui-tools/map` entry is already the **lazy** one — `LazyMapContainer` defers the MapLibre chunk until it mounts. All components are `'use client'`; never render them on the Next.js server.
 
 ## Quick start
 
 ```tsx
-import { MapContainer, MapMarker } from '@djangocfg/ui-tools/map';
+import { LazyMapContainer, MapMarker } from '@djangocfg/ui-tools/map';
 
 <div className="h-96 rounded-xl overflow-hidden">
-  <MapContainer
+  <LazyMapContainer
     initialViewport={{ latitude: 25.08, longitude: 55.14, zoom: 13 }}
     mapStyle="light"
   >
@@ -19,366 +19,51 @@ import { MapContainer, MapMarker } from '@djangocfg/ui-tools/map';
       color="#10b981"
       size={32}
     />
-  </MapContainer>
+  </LazyMapContainer>
 </div>
 ```
 
-The container provides its own `MapProvider`. If you need the map context outside `MapContainer` (for example to call `flyTo` on a sibling button), wrap your tree in `<MapProvider>` and use `<MapView>` inside it instead.
+The container provides its own `MapProvider`. To use the map context from a sibling (e.g. a button calling `flyTo`), wrap your tree in `<MapProvider>` and render `<MapView>` inside it. See [container](./@docs/container.md).
 
-## Public exports
+## Public exports — `@djangocfg/ui-tools/map`
 
-### Components
+The package subpath resolves to the lazy entry. It surfaces:
 
-| Export | Notes |
-|---|---|
-| `MapContainer` | Self-contained map: `MapProvider` + `MapView` + reset / open-in-maps overlay buttons |
-| `MapView` | Inner map only — must live inside an existing `<MapProvider>` |
-| `MapProvider` | Context provider (viewport, ref, markers, hover state, isLoaded) |
-| `MapMarker` | DOM marker with default pin, custom children, drag |
-| `MapPopup` | MapLibre popup wrapper |
-| `MapCluster` | GeoJSON source + cluster/point layers + click-to-zoom + optional render-prop popup |
-| `MapSource` / `MapLayer` | Thin GeoJSON `Source` + `Layer` re-exports |
-| `MapControls` | NavigationControl / Fullscreen / Geolocate / Scale toggles |
-| `CustomOverlay` | DOM overlay that re-renders on `move` (uses `useControl` + portal) |
-| `MapLegend` | Floating legend with circle / line / fill / symbol icons |
-| `LayerSwitcher` | Floating checkbox panel that toggles layer visibility |
-
-### Hooks
-
-| Hook | Returns |
-|---|---|
-| `useMap()` | Full map context (alias for `useMapContext`) |
-| `useMapContext()` | Same — throws if used outside `<MapProvider>` |
-| `useMapControl()` | `flyTo` / `easeTo` / `fitBounds` / `zoomIn` / `zoomOut` / `resetView` / `getCenter` / `getZoom` / `getBounds` |
-| `useMapViewport()` | `{ viewport, setViewport, animateTo, zoom, center, bounds }` |
-| `useMarkers()` | `addMarker` / `removeMarker` / `updateMarker` / `clearMarkers` / `fitToMarkers` |
-| `useMapEvents(handlers)` | Subscribe to `click` / `hover` / `move*` / `zoom*` / `load` with cleanup |
-| `useMapLayers()` | `addLayer` / `removeLayer` / `setLayerVisibility` / `setLayerFilter` / `setLayerPaint` |
-| `useSpiderfy(markers, opts?)` | Auto-offset overlapping markers; optional click-to-expand |
-| `useControl(...)` | Re-exported from `react-map-gl/maplibre` for custom controls |
-
-### Layer factories
-
-`createClusterLayers`, `createPointLayer`, `createHeatmapLayer`, `createPolygonLayer`, `createPolygonOutlineLayer`, `createHighlightLayer`, `createLineLayer`, `createRouteLayers`, `createDashedLineLayer`, `createAnimatedLineLayer`.
-
-### Geometry utils
-
-`calculateBounds`, `calculateCenter`, `calculateDistance` (Haversine, km), `isPointInBounds`, `expandBounds`, `toGeoJSON`, `fromGeoJSON`, `createPoint`, `createPolygon`, `createLineString`, `createFeatureCollection`.
-
-### Spiderfy utils
-
-`offsetOverlappingMarkers`, `getSpiderfyPositions`, `groupOverlappingMarkers`, `hasOverlappingMarkers`, `getOverlapStats`.
-
-### Styles
-
-`MAP_STYLES`, `getMapStyle(key)`.
-
-### Re-exports from `react-map-gl/maplibre`
-
-`Source`, `Layer`, `Marker`, `Popup`, types `ViewState` and `MapRef`.
-
-## `MapContainer` props
-
-| Prop | Type | Default | Notes |
-|---|---|---|---|
-| `initialViewport` | `Partial<MapViewport>` | `{ longitude: 115.1889, latitude: -8.4095, zoom: 10 }` | Bali fallback. Provide your own. |
-| `mapStyle` | `MapStyleKey \| string` | `'light'` | Built-in key or full style URL/object |
-| `interactiveLayerIds` | `string[]` | — | Layer ids that emit `click` / `hover` events |
-| `attributionControl` | `boolean` | `true` | |
-| `reuseMaps` | `boolean` | `true` | Reuse the canvas across remounts (faster Storybook / route changes) |
-| `cursor` | `string` | — | Cursor while not dragging |
-| `style` | `CSSProperties` | — | Forwarded to inner `<Map>` (size, etc.) |
-| `className` | `string` | — | Outer wrapper `<div>` |
-| `openInMapsUrl` | `string` | — | Renders an "Open in Maps" pill in the bottom-right |
-| `openInMapsLabel` | `string` | `'Open in Maps'` | |
-| `showResetButton` | `boolean` | `false` | Shows a reset pill once the user has panned/zoomed away from `initialViewport` |
-| `autoResetDelay` | `number` (ms) | `0` | After this many ms of inactivity, fly back to `initialViewport`. `0` disables. |
-
-`MapView` accepts every prop above except `initialViewport` (which lives on the surrounding `MapProvider`).
-
-## Markers
-
-```tsx
-<MapMarker
-  marker={{ id: 'pin', longitude: 2.35, latitude: 48.85, data: { city: 'Paris' } }}
-  color="#3b82f6"
-  size={28}
-  anchor="bottom"
-  draggable
-  onClick={(m) => console.log(m.id)}
-  onDragEnd={(m, lngLat) => save(m.id, lngLat)}
-/>
-```
-
-Pass `children` to replace the default SVG pin entirely:
-
-```tsx
-<MapMarker marker={pin}>
-  <div className="size-8 rounded-full bg-primary text-white grid place-items-center">
-    {pin.data?.count}
-  </div>
-</MapMarker>
-```
-
-`MarkerData` is intentionally minimal: `{ id, longitude, latitude, data? }`. Carry your domain payload in `data` — markers are generic over what's there.
-
-## Popups
+**Components** — `LazyMapContainer`, `LazyMapView` (code-split), `MapView`-via-`MapContainer` types, plus the light primitives: `MapMarker`, `MapPopup`, `MapCluster`, `MapSource`, `MapLayer`, `MapControls`, `CustomOverlay`, `MapLegend`, `LayerSwitcher`, `MeasureControl`, `DraggableMarkers`, `GeocoderInput`, `GeocoderControl`, `CompassChip`, `MarkerCard`, `MapMarkers`.
 
-```tsx
-<MapPopup
-  longitude={loc.lng}
-  latitude={loc.lat}
-  onClose={() => setSelected(null)}
-  anchor="bottom"
-  offset={20}
->
-  <div className="p-3">…</div>
-</MapPopup>
-```
-
-For "click marker → fly to it → open popup" flow, use `useMapControl().flyTo` from a component nested inside `<MapProvider>` (see `Map.story.tsx` → `WithPopup`).
-
-## Clustering
-
-`MapCluster` mounts a clustered GeoJSON source with three layers (cluster bubbles, count labels, unclustered points), wires click + hover handlers, and optionally renders a popup via render prop.
-
-```tsx
-<MapCluster
-  sourceId="properties"
-  data={featureCollection}
-  clusterRadius={60}
-  clusterMaxZoom={14}
-  colors={['#3b82f6', '#8b5cf6', '#ec4899']}
-  onPointClick={(feature) => setSelected(feature)}
-  renderPopup={(feature, close) => (
-    <Card>
-      <h3>{feature.properties?.name}</h3>
-      <button onClick={close}>Close</button>
-    </Card>
-  )}
-  popupAnchor="bottom"
-  popupOffset={15}
-/>
-```
-
-Click on a cluster zooms to its expansion zoom. Hover sets `feature-state.hover` so you can tint the bubble in your paint expressions.
-
-### Overlapping points
-
-When several features share a coordinate (e.g. multiple units in one building), pre-process the source so they're individually clickable when unclustered:
+**Context** — `MapProvider`, `useMapContext`, `MapContext`.
 
-```tsx
-import { offsetOverlappingMarkers } from '@djangocfg/ui-tools/map';
-
-const data = useMemo(() => {
-  const markers = features.map((f, i) => ({
-    id: f.properties?.id ?? `p-${i}`,
-    longitude: f.geometry.coordinates[0],
-    latitude: f.geometry.coordinates[1],
-    data: f.properties,
-  }));
-  const offset = offsetOverlappingMarkers(markers, { spiralRadius: 0.0003 });
-  return {
-    type: 'FeatureCollection' as const,
-    features: offset.map((m) => ({
-      type: 'Feature' as const,
-      properties: m.data,
-      geometry: { type: 'Point' as const, coordinates: [m.longitude, m.latitude] },
-    })),
-  };
-}, [features]);
-```
+**Styles** — `MAP_STYLES`, `getMapStyle`, `MAP_STYLE_LABELS`, `KEY_FREE_STYLES`, `resolveBasemapOptions`, and the free terrain DEM source `TERRAIN_DEM` / `TERRAIN_DEM_URL`.
 
-`offsetOverlappingMarkers` uses a Fermat spiral by default; pass `useJitter: true` for randomised offsets keyed on marker `id`. The `useSpiderfy` hook wraps this with React state and an optional click-to-expand mode.
+**PMTiles** — `addPMTilesProtocol`, `pmtilesSourceUrl` (self-hosted / offline basemaps).
 
-## Layers
+**Geocoder** — `photonResolve` (default key-free Photon resolver), `cameraForResult` (smart-zoom helper), and types `GeocodeResult`, `GeocodeKind`, `ResolveGeocode`. See [geocoder](./@docs/geocoder.md).
 
-Drop a `MapSource` + `MapLayer` for raw GeoJSON, or use the layer factories for typed defaults:
-
-```tsx
-import {
-  MapSource, MapLayer,
-  createPolygonLayer, createPolygonOutlineLayer,
-} from '@djangocfg/ui-tools/map';
-
-<MapSource id="zones" data={polygonGeoJson}>
-  <MapLayer {...createPolygonLayer({ fillColor: '#10b981', fillOpacity: 0.2 })} />
-  <MapLayer {...createPolygonOutlineLayer({ strokeColor: '#10b981', strokeWidth: 2 })} />
-</MapSource>
-```
-
-Available factories: `createClusterLayers`, `createPointLayer`, `createHeatmapLayer`, `createPolygonLayer`, `createPolygonOutlineLayer`, `createHighlightLayer`, `createLineLayer`, `createRouteLayers`, `createDashedLineLayer`, `createAnimatedLineLayer`.
-
-## Map styles
-
-Four built-in keys, all served from public CDNs (no API key needed except `satellite`, which uses MapTiler):
-
-| Key | Source |
-|---|---|
-| `light` | CartoCDN Positron |
-| `dark` | CartoCDN Dark Matter |
-| `streets` | CartoCDN Voyager |
-| `satellite` | MapTiler Satellite (replace with your own key in production) |
-
-```tsx
-import { MAP_STYLES, getMapStyle } from '@djangocfg/ui-tools/map';
-
-<MapContainer mapStyle="dark" />
-<MapContainer mapStyle="https://your-cdn.example/style.json" />
-<MapContainer mapStyle={getMapStyle(userPref)} />
-```
-
-## Hooks
-
-All hooks must be called inside `<MapProvider>` (which `MapContainer` provides automatically).
-
-### `useMapControl()`
-
-Imperative camera control. All animations have sensible defaults (`flyTo` 2 s, `easeTo` 0.5 s, `fitBounds` 1 s, padding 50 px).
-
-```tsx
-const { flyTo, fitBounds, zoomIn, getBounds } = useMapControl();
-flyTo([lng, lat], 14, { duration: 1500 });
-fitBounds([[w, s], [e, n]], { padding: 80 });
-```
-
-### `useMapViewport()`
-
-Reactive viewport state plus an `animateTo` shortcut.
-
-```tsx
-const { viewport, animateTo, bounds } = useMapViewport();
-animateTo({ latitude: 0, longitude: 0, zoom: 2 }, 800);
-```
-
-### `useMarkers()`
-
-Manages markers held by `MapProvider` (separate from any `<MapMarker>` you render manually). Generates ids automatically.
-
-```tsx
-const { addMarker, fitToMarkers, clearMarkers } = useMarkers();
-const id = addMarker({ longitude, latitude, data: { kind: 'pickup' } });
-fitToMarkers(80);
-```
-
-### `useMapEvents(handlers)`
-
-Attaches handlers to the underlying MapLibre map once it's loaded; cleans up on unmount or when handlers change.
-
-```tsx
-useMapEvents({
-  onClick: (e) => console.log(e.lngLat, e.features),
-  onMoveEnd: (vp) => persistViewport(vp),
-  onZoomEnd: (z) => setZoom(z),
-});
-```
-
-### `useMapLayers()`
-
-Imperative layer mutation — for layers added at runtime via `addLayer`, or for tweaking declarative `<MapLayer>` instances by id.
-
-```tsx
-const { setLayerVisibility, setLayerFilter, setLayerPaint } = useMapLayers();
-setLayerVisibility('zones-fill', visible);
-setLayerFilter('zones-fill', ['==', ['get', 'status'], 'active']);
-```
-
-### `useSpiderfy(markers, options?)`
-
-Higher-level than `offsetOverlappingMarkers`: returns processed markers, expansion state, and `expandGroup` / `collapseGroup` callbacks.
-
-```tsx
-const { markers, expandGroup, isExpanded } = useSpiderfy(rawMarkers, {
-  spiralRadius: 0.0002,
-  expandOnClick: true,
-});
-```
-
-## Geometry utilities
-
-```tsx
-import {
-  calculateBounds, calculateCenter, calculateDistance,
-  expandBounds, isPointInBounds,
-  toGeoJSON, fromGeoJSON,
-  createPoint, createPolygon, createLineString, createFeatureCollection,
-} from '@djangocfg/ui-tools/map';
-
-const bounds = calculateBounds(points.map((p) => [p.lng, p.lat]));
-const km = calculateDistance([fromLng, fromLat], [toLng, toLat]); // Haversine
-const fc = toGeoJSON(items, (i) => [i.lng, i.lat], (i) => ({ name: i.name }));
-
-useMapControl().fitBounds(expandBounds(bounds, 10), { padding: 50 });
-```
-
-## Floating UI
-
-`MapLegend` and `LayerSwitcher` are absolutely-positioned panels (`top-left` / `top-right` / `bottom-left` / `bottom-right`). They use inline styles for portability — wrap them in your own component if you want shadcn theming.
-
-```tsx
-<MapLegend
-  title="Activity"
-  position="bottom-left"
-  collapsible
-  items={[
-    { id: 'high', label: 'High', color: '#ef4444', type: 'circle' },
-    { id: 'low',  label: 'Low',  color: '#3b82f6', type: 'circle' },
-  ]}
-/>
-
-<LayerSwitcher
-  position="top-right"
-  showToggleAll
-  layers={[
-    { id: 'zones-fill', label: 'Zones', defaultVisible: true },
-    { id: 'routes-line', label: 'Routes', defaultVisible: false },
-  ]}
-  onChange={(id, visible) => console.log(id, visible)}
-/>
-```
-
-## DrawControl & GeocoderControl
-
-These are documentation stubs — both rely on optional peer deps and are easy to wire by hand:
-
-- `DrawControl` → `npm i @mapbox/mapbox-gl-draw`
-- `GeocoderControl` → `npm i @maplibre/maplibre-gl-geocoder` + an HTTP geocoder (Nominatim, Photon, your backend)
-
-See the JSDoc in `components/DrawControl.tsx` and `components/GeocoderControl.tsx` for ready-to-paste implementations using the re-exported `useControl` hook.
-
-## Lazy loading
-
-```tsx
-import { LazyMapContainer } from '@djangocfg/ui-tools/map/lazy';
-
-<LazyMapContainer
-  initialViewport={{ latitude: 0, longitude: 0, zoom: 2 }}
-  mapStyle="light"
-/>
-```
+**Types** — `MapContainerProps`, `GeolocateOptions`, `GeolocatePosition`, `MapMarkerProps`, `MapPopupProps`, `MapClusterProps`, `MapSourceProps`, `MapLayerProps`, `MapControlsProps`, `MeasureControlProps`, `DraggableMarkersProps`, `DraggablePoint`, `GeocoderInputProps`, `GeocoderControlProps`, `CompassChipProps`, `MapProviderProps`, `MapViewport`, `MapStyleKey`, `MarkerData`, plus hook types `GeolocationFix`, `GeolocationStatus`, `UseGeolocationOptions`, `UseGeolocationResult`, `UseGeocoderOptions`, `UseGeocoderResult`, `UseCompassResult`, `UseTerrainOptions`, `UseMeasureResult`, `MeasureMode`, `MapImage`, `UseMapImagesResult`, `UseDraggableMarkersOptions`, `UseDraggableMarkersResult`, `DraggableMarkerHandlers`, plus the marker-card types `MarkerCardProps`, `MapMarkersProps`, `MarkerWithCard`, `MarkerCardInfo` (the card data shape), `MarkerCardAction`, `MarkerCardData`, `MarkerCardActionData`, `UseMarkerCardResult`.
 
-`LazyMapContainer` and `LazyMapView` defer the MapLibre GL chunk until the component renders. They show a built-in `MapLoadingFallback` (skeleton, `minHeight={400}`) while the chunk is in-flight. Prefer the lazy variants on routes where the map is below the fold or behind a tab.
+**Hooks** — `useMap`, `useMapControl`, `useMarkers`, `useMapEvents`, `useMapViewport`, `useMapLayers`, `useControl`, `useSpiderfy` (+ `UseSpiderfyOptions` / `UseSpiderfyResult` types), `useMarkerCard` (single-open marker-card selection state), the feature hooks `useCompass`, `useTerrain`, `useMeasure`, `useMapImages`, `useDraggableMarkers`, `useGeocoder`, and the map-independent `useGeolocation` (live browser position for custom "where am I" UI; see [hooks](./@docs/hooks.md#usegeolocationoptions)). `useMapScrollProtection` / `useMapTouchMode` are also exported — they power `scrollProtection`, which wires them for you.
 
-## SSR
+**Layer factories** — `createClusterLayers`, `createPointLayer`, `createHeatmapLayer`, `createPolygonLayer`, `createPolygonOutlineLayer`, `createHighlightLayer`, `createLineLayer`, `createRouteLayers`, `createDashedLineLayer`, `createAnimatedLineLayer`, `createSymbolLayer`.
 
-Every component is `'use client'` and depends on `window`. In Next.js App Router this is fine — they will only render on the client. In the Pages Router or any custom SSR setup, gate them with `dynamic(() => …, { ssr: false })` or use the lazy variants from `./lazy`.
+**Geometry utils** — `calculateBounds`, `calculateCenter`, `calculateDistance`, `isPointInBounds`, `expandBounds`, `toGeoJSON`, `fromGeoJSON`, `createPoint`, `createPolygon`, `createLineString`, `createFeatureCollection`.
 
-## Stories
+**Spiderfy utils** — `offsetOverlappingMarkers`, `getSpiderfyPositions`, `groupOverlappingMarkers`, `hasOverlappingMarkers`, `getOverlapStats`.
 
-Run `pnpm playground` from `packages/ui-tools/`. Map stories in `Map.story.tsx`:
+## Docs
 
-| Story | Demonstrates |
+| Doc | Covers |
 |---|---|
-| `Interactive` | Style switcher + zoom + reset button + auto-reset |
-| `PropertyCard` | Embedded compact map inside a card |
-| `DarkStyle` | `mapStyle="dark"` |
-| `MultipleMarkers` | World view with several pins |
-| `WithAutoReset` | `autoResetDelay={3000}` |
-| `WithPopup` | `useMapControl().flyTo` + `<MapPopup>` |
-| `SpiderfyCluster` | `MapCluster` + `offsetOverlappingMarkers` |
+| [container.md](./@docs/container.md) | `MapContainer` / `MapView` — full props, control toolbar (search · terrain · compass · locate-me / GPS chips), scroll protection & mobile, fullscreen dialog. |
+| [basemaps.md](./@docs/basemaps.md) | Map styles, the runtime basemap switcher, OpenFreeMap, satellite/keys, PMTiles, 3D terrain (free DEM). |
+| [markers-popups.md](./@docs/markers-popups.md) | `MapMarker`, `MapPopup`, `MapCluster`, marker info-cards (`MarkerCard` / `MapMarkers` / `useMarkerCard`), draggable markers, overlapping points / spiderfy. |
+| [layers.md](./@docs/layers.md) | `MapSource` / `MapLayer`, the layer factories, custom marker icons (symbol layer), geometry utilities. |
+| [geocoder.md](./@docs/geocoder.md) | Address/place autocomplete — `GeocoderInput` / `GeocoderControl`, the toolbar search chip, `photonResolve`, smart zoom (`cameraForResult`), `useGeocoder`. |
+| [hooks.md](./@docs/hooks.md) | Every hook, with an example. |
+| [advanced.md](./@docs/advanced.md) | `CustomOverlay`, `MapLegend`, `LayerSwitcher`, `MeasureControl`, the DrawControl recipe, lazy loading, SSR. |
+| [stories.md](./@docs/stories.md) | The Storybook stories list. |
 
 ## Related
 
-- Public surface: `src/tools/Map/index.ts`
-- Lazy preset: `src/tools/Map/lazy.tsx`
+- Public entry: `lazy.tsx` (what `@djangocfg/ui-tools/map` resolves to)
+- Full barrel: `index.ts` — the subpath re-exports the same light surface (hooks, layer factories, geometry + spiderfy utils, styles, PMTiles helpers).
 - Underlying lib: [`react-map-gl` (MapLibre adapter)](https://visgl.github.io/react-map-gl/) on top of [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/)

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

@@ -0,0 +1,6 @@
+export type {
+  MarkerCard,
+  MarkerCardAction,
+  MarkerCardData,
+  MarkerCardActionData,
+} from './types'

package/src/tools/dev/Map/cards/types.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Marker info-card data — the Google-Maps-style card that opens above a pin.
+ *
+ * This is the FULL, in-app shape. The SERIALIZABLE subset (everything except
+ * the function/React parts of `actions`) is what the chat `MapBlock` wire
+ * format reuses — see `MarkerCardData` below and `MapBlock.markers[].card`.
+ */
+export interface MarkerCard {
+  /** Primary heading (required). */
+  title: string
+  /** Supporting copy, clamped to ~3 lines in the default card. */
+  description?: string
+  /** Image URL rendered as a rounded header (object-cover). */
+  image?: string
+  /** Small pill above the title (e.g. a category). */
+  badge?: string
+  /** Action row — buttons/links rendered below the body. */
+  actions?: MarkerCardAction[]
+}
+
+/**
+ * A single action in a card's action row.
+ *
+ * Provide `href` for a link (renders an `<a>`) OR `onClick` for an in-app
+ * callback (renders a `<button>`). `icon`/`onClick` are function/React parts
+ * that do NOT cross the chat wire — the serializable subset is href-only.
+ */
+export interface MarkerCardAction {
+  /** Visible label. */
+  label: string
+  /** Link target → renders an anchor. */
+  href?: string
+  /** In-app callback → renders a button. Ignored when `href` is set. */
+  onClick?: () => void
+  /** Optional leading icon. */
+  icon?: ReactNode
+  /** Button style — maps to ui-core Button variants. */
+  variant?: 'default' | 'outline' | 'ghost'
+}
+
+// ============================================================================
+// Serializable subset — the chat wire shape
+// ============================================================================
+
+/**
+ * Plain-JSON action — the wire subset of {@link MarkerCardAction}. No
+ * `onClick`/`icon` (functions/React don't serialize); links only.
+ */
+export interface MarkerCardActionData {
+  label: string
+  href?: string
+}
+
+/**
+ * Plain-JSON card — the wire subset of {@link MarkerCard}. Strings/URLs only,
+ * actions are href-only. Carried by the chat `MapBlock` so a marker can open
+ * a card with no host code. Assignable to {@link MarkerCard}.
+ */
+export interface MarkerCardData {
+  title: string
+  description?: string
+  image?: string
+  badge?: string
+  actions?: MarkerCardActionData[]
+}

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

@@ -0,0 +1,67 @@
+'use client'
+
+import { Compass } from 'lucide-react'
+import { cn } from '@djangocfg/ui-core/lib'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core/components'
+
+import { MAP_CONTROL_CLASS } from './MapContainer/constants'
+
+export interface CompassChipProps {
+  /** Current camera bearing in degrees; the needle counter-rotates by this. */
+  bearing: number
+  /**
+   * Whether the view is rotated/tilted off true north. Drives the color cue:
+   * an accent needle (Google's gray→red "you're off-north") when oriented,
+   * the neutral chip foreground otherwise. The chip is typically only rendered
+   * while oriented (the caller gates it), so the visible needle reads accent.
+   */
+  oriented: boolean
+  /** Click handler — ease the camera back to a north-up, top-down view. */
+  onReset: () => void
+  /** Accessible / tooltip label. @default 'Reset bearing to north' */
+  label?: string
+  /** Extra classes merged onto the chip button. */
+  className?: string
+}
+
+/**
+ * Compass chip — a Google-Maps-style reset-to-north control.
+ *
+ * Presentational: the needle counter-rotates by `bearing` so it keeps
+ * pointing at true north as the map turns underneath it, and it tints to an
+ * ACCENT (`text-primary`) when `oriented` to signal "you're off true north"
+ * (our semantic stand-in for Google's red needle). Click eases the camera
+ * back to north-up + top-down via `onReset`. Keyboard-reachable; the chip
+ * lives inside the toolbar's `data-map-control` region so it never re-locks
+ * scroll. Mirrors the terrain/geolocate chip pattern (`MAP_CONTROL_CLASS`,
+ * `Tooltip`, semantic tokens only).
+ */
+export function CompassChip({
+  bearing,
+  oriented,
+  onReset,
+  label = 'Reset bearing to north',
+  className,
+}: CompassChipProps) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          onClick={onReset}
+          aria-label={label}
+          className={cn(MAP_CONTROL_CLASS, 'w-9 h-9', oriented && 'text-primary', className)}
+        >
+          <Compass
+            className="w-4 h-4"
+            aria-hidden="true"
+            // Counter-rotate the needle so it points to true north as the
+            // map rotates underneath it.
+            style={{ transform: `rotate(${-bearing}deg)` }}
+          />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="left">{label}</TooltipContent>
+    </Tooltip>
+  )
+}

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

@@ -0,0 +1,79 @@
+'use client'
+
+import { memo, type ReactNode } from 'react'
+
+import { MapMarker } from './MapMarker'
+import {
+  useDraggableMarkers,
+  type DraggablePoint,
+} from '../hooks/useDraggableMarkers'
+import type { MarkerData } from '../types'
+
+export type { DraggablePoint }
+
+export interface DraggableMarkersProps {
+  /** Controlled list of draggable positions. */
+  positions: DraggablePoint[]
+  /**
+   * Fires with the full, updated array when a marker is dropped (drag-end).
+   * The host persists `next` and feeds it back via `positions`.
+   */
+  onChange: (next: DraggablePoint[]) => void
+  /** Optional live callback fired on every drag frame (not committed). */
+  onDragMove?: (id: string, lng: number, lat: number) => void
+  /** Pin color (passed through to `MapMarker`). */
+  color?: string
+  /** Pin size in px (passed through to `MapMarker`). */
+  size?: number
+  /** Custom marker renderer; replaces the default pin. */
+  renderMarker?: (marker: MarkerData) => ReactNode
+}
+
+/**
+ * Thin controlled component that renders one draggable `MapMarker` per
+ * position. Must be mounted inside `<MapProvider>` (i.e. as a child of
+ * `MapContainer` / `MapView`), like `MapLegend`.
+ *
+ * Dragging a pin commits its new `{ lng, lat }` through `onChange`. The
+ * maplibre `LngLat` object delivered by the drag callbacks is normalized to
+ * plain numbers inside `useDraggableMarkers`.
+ */
+function DraggableMarkersComponent({
+  positions,
+  onChange,
+  onDragMove,
+  color,
+  size,
+  renderMarker,
+}: DraggableMarkersProps) {
+  const { markers, getHandlers } = useDraggableMarkers({
+    positions,
+    onChange,
+    onDragMove,
+  })
+
+  return (
+    <>
+      {markers.map((marker) => {
+        const handlers = getHandlers(marker.id)
+        return (
+          <MapMarker
+            key={marker.id}
+            marker={marker}
+            draggable
+            color={color}
+            size={size}
+            ariaLabel={`Draggable marker ${marker.id}`}
+            onDragStart={handlers.onDragStart}
+            onDrag={handlers.onDrag}
+            onDragEnd={handlers.onDragEnd}
+          >
+            {renderMarker ? renderMarker(marker) : undefined}
+          </MapMarker>
+        )
+      })}
+    </>
+  )
+}
+
+export const DraggableMarkers = memo(DraggableMarkersComponent)