@dxos/react-ui-geo 0.8.4-staging.ac66bdf99f → 0.9.0

package/src/components/Map/Map.tsx

@@ -5,13 +5,31 @@
 import 'leaflet/dist/leaflet.css';
 
 import { createContext } from '@radix-ui/react-context';
-import L, { Control, type ControlPosition, DomEvent, DomUtil, type LatLngLiteral, latLngBounds } from 'leaflet';
-import React, { type PropsWithChildren, forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import L, { Control, type ControlPosition, DomEvent, DomUtil, type LatLngLiteral, point, latLngBounds } from 'leaflet';
+import React, {
+  type PropsWithChildren,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
 import { createRoot } from 'react-dom/client';
-import { MapContainer, type MapContainerProps, Marker, Popup, TileLayer, useMap, useMapEvents } from 'react-leaflet';
+import {
+  MapContainer,
+  type MapContainerProps,
+  Marker,
+  Polyline,
+  Popup,
+  TileLayer,
+  useMap,
+  useMapEvents,
+} from 'react-leaflet';
 
 import { type ThemedClassName, ThemeProvider, Tooltip } from '@dxos/react-ui';
-import { composable, composableProps, defaultTx, mx } from '@dxos/ui-theme';
+import { composable, composableProps, defaultTx } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
 import { type GeoMarker } from '../../types';
 import { ActionControls, type ControlProps, ZoomControls, controlPositions } from '../Toolbar';
@@ -30,6 +48,8 @@ const defaults = {
 //
 
 type MapController = {
+  getCenter: () => LatLngLiteral | undefined;
+  getZoom: () => number | undefined;
   setCenter: (center: LatLngLiteral, zoom?: number) => void;
   setZoom: (cb: (zoom: number) => number) => void;
 };
@@ -41,33 +61,50 @@ type MapController = {
 type MapContextValue = {
   attention?: boolean;
   onChange?: (ev: { center: LatLngLiteral; zoom: number }) => void;
+  /** Called by Map.Viewport to register/unregister the leaflet map with the controller owned by Map.Root. */
+  registerMap: (map: L.Map | null) => void;
 };
 
 const [MapContextProvider, useMapContext] = createContext<MapContextValue>('Map');
 
 //
-// Root
+// Root — headless; owns the imperative MapController (exposed via ref) and the map registry.
 //
 
-type MapRootProps = Pick<MapContextValue, 'onChange'>;
+type MapRootProps = PropsWithChildren<Pick<MapContextValue, 'onChange'>>;
 
 /**
- * Context provider for the map. Must wrap Map.Content.
+ * Context provider for the map. Must wrap Map.Viewport. The ref exposes a {@link MapController}.
  */
-const MapRoot = composable<HTMLDivElement, MapRootProps>(({ children, onChange, ...props }, forwardedRef) => {
+const MapRoot = forwardRef<MapController, MapRootProps>(({ children, onChange }, forwardedRef) => {
+  const mapRef = useRef<L.Map | null>(null);
+  const registerMap = useCallback((map: L.Map | null) => {
+    mapRef.current = map;
+  }, []);
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      getCenter: () => {
+        const center = mapRef.current?.getCenter();
+        return center ? { lat: center.lat, lng: center.lng } : undefined;
+      },
+      getZoom: () => mapRef.current?.getZoom(),
+      setCenter: (center: LatLngLiteral, zoom?: number) => {
+        mapRef.current?.setView(center, zoom);
+      },
+      setZoom: (cb: (zoom: number) => number) => {
+        mapRef.current?.setZoom(cb(mapRef.current?.getZoom() ?? 0));
+      },
+    }),
+    [],
+  );
+
   // TODO(burdon): Use attention: const [attention, setAttention] = useState(false);
   const attention = false;
   return (
-    <MapContextProvider attention={attention} onChange={onChange}>
-      <div
-        {...composableProps(props, {
-          role: 'none',
-          classNames: 'dx-container grid dx-focus-ring-inset',
-        })}
-        ref={forwardedRef}
-      >
-        {children}
-      </div>
+    <MapContextProvider attention={attention} onChange={onChange} registerMap={registerMap}>
+      {children}
     </MapContextProvider>
   );
 });
@@ -75,74 +112,161 @@ const MapRoot = composable<HTMLDivElement, MapRootProps>(({ children, onChange,
 MapRoot.displayName = 'Map.Root';
 
 //
-// Content
+// Viewport
 //
 
-type MapContentProps = ThemedClassName<Omit<MapContainerProps, 'children'> & PropsWithChildren>;
+type MapViewportProps = ThemedClassName<Omit<MapContainerProps, 'children'> & PropsWithChildren>;
 
 /**
  * https://react-leaflet.js.org/docs/api-map
  */
-const MAP_CONTENT_NAME = 'Map.Content';
+const MAP_VIEWPORT_NAME = 'Map.Viewport';
 
-const MapContent = forwardRef<MapController, MapContentProps>(
-  (
-    { classNames, scrollWheelZoom = true, doubleClickZoom = true, touchZoom = true, center, zoom, children, ...props },
-    forwardedRef,
-  ) => {
-    const { attention } = useMapContext(MAP_CONTENT_NAME);
-    const mapRef = useRef<L.Map>(null);
-    const map = mapRef.current;
-
-    useImperativeHandle(
-      forwardedRef,
-      () => ({
-        setCenter: (center: LatLngLiteral, zoom?: number) => {
-          mapRef.current?.setView(center, zoom);
-        },
-        setZoom: (cb: (zoom: number) => number) => {
-          mapRef.current?.setZoom(cb(mapRef.current?.getZoom() ?? 0));
-        },
-      }),
-      [],
-    );
+/**
+ * Recalculates the leaflet map size when its container resizes (e.g. a companion
+ * panel opening/closing). Without this, leaflet keeps its stale size and renders
+ * blank/gray tiles in the newly-exposed area until the next pan/zoom. Coalesced
+ * via rAF to avoid ResizeObserver feedback loops.
+ */
+const MapResize = () => {
+  const map = useMap();
+  useEffect(() => {
+    const container = map.getContainer();
+    let frame = 0;
+    const observer = new ResizeObserver(() => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => map.invalidateSize());
+    });
+    observer.observe(container);
+    return () => {
+      cancelAnimationFrame(frame);
+      observer.disconnect();
+    };
+  }, [map]);
+
+  return null;
+};
+
+/**
+ * Enables pinch-to-zoom on trackpads / ctrl+wheel. Browsers deliver a trackpad pinch as a `wheel`
+ * event with `ctrlKey` set; Leaflet only zooms those via `scrollWheelZoom`, which is intentionally
+ * off here (so plain scrolling doesn't hijack the page). This handler zooms on the pinch gesture
+ * only, leaving normal wheel scrolling untouched. (Touchscreen pinch is handled by Leaflet's
+ * `touchZoom`.)
+ */
+// Zoom levels per pixel of pinch (ctrl+wheel) delta.
+const PINCH_ZOOM_SENSITIVITY = 0.03;
 
-    // Enable/disable scroll wheel zoom.
-    // TODO(burdon): Use attention:
-    // const {hasAttention} = useAttention(props.id);
-    useEffect(() => {
-      if (!map) {
+const MapPinchZoom = () => {
+  const map = useMap();
+  useEffect(() => {
+    const container = map.getContainer();
+    let frame = 0;
+    let point: ReturnType<typeof L.point> | undefined;
+    // Accumulate the target against the last requested value (not the live, mid-zoom `getZoom()`)
+    // and apply once per animation frame without zoom animation — overlapping animated zooms are
+    // what made this jittery. Reset between frames so the next batch re-reads the settled zoom.
+    let target: number | undefined;
+
+    const onWheel = (event: WheelEvent) => {
+      if (!event.ctrlKey) {
         return;
       }
-
-      if (attention) {
-        map.scrollWheelZoom.enable();
-      } else {
-        map.scrollWheelZoom.disable();
+      event.preventDefault();
+      const rect = container.getBoundingClientRect();
+      point = L.point(event.clientX - rect.left, event.clientY - rect.top);
+      target = (target ?? map.getZoom()) - event.deltaY * PINCH_ZOOM_SENSITIVITY;
+      if (!frame) {
+        frame = requestAnimationFrame(() => {
+          frame = 0;
+          if (target !== undefined && point) {
+            map.setZoomAround(point, target, { animate: false });
+            target = undefined;
+          }
+        });
       }
-    }, [map, attention]);
-
-    return (
-      <MapContainer
-        {...props}
-        className={mx('group relative grid bg-base-surface!', classNames)}
-        attributionControl={false}
-        zoomControl={false}
-        scrollWheelZoom={scrollWheelZoom}
-        doubleClickZoom={doubleClickZoom}
-        touchZoom={touchZoom}
-        center={center ?? defaults.center}
-        zoom={zoom ?? defaults.zoom}
-        whenReady={() => {}}
-        ref={mapRef}
-      >
-        {children}
-      </MapContainer>
-    );
-  },
-);
+    };
+
+    container.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+      container.removeEventListener('wheel', onWheel);
+      cancelAnimationFrame(frame);
+    };
+  }, [map]);
+
+  return null;
+};
+
+/**
+ * Map.Viewport is the focusable Leaflet frame. It can be the target of a parent `<Panel.Content asChild>`
+ * (Slot), so it reconciles an injected `className` via `composableProps`. Leaflet owns the underlying
+ * container element, so the forwarded DOM ref can't be attached and is intentionally unused.
+ */
+const MapViewport = composable<HTMLDivElement, MapViewportProps>((props, _forwardedRef) => {
+  const {
+    scrollWheelZoom = true,
+    doubleClickZoom = true,
+    touchZoom = true,
+    center,
+    zoom,
+    whenReady,
+    children,
+    ...rest
+  } = props;
+  const { attention, registerMap } = useMapContext(MAP_VIEWPORT_NAME);
+  // Local copy of the leaflet map for this component's own effects; also registered with Map.Root.
+  const [map, setMap] = useState<L.Map | null>(null);
+
+  // Register/unregister the map with the controller owned by Map.Root.
+  const setMapRef = useCallback(
+    (next: L.Map | null) => {
+      setMap(next);
+      registerMap(next);
+    },
+    [registerMap],
+  );
 
-MapContent.displayName = 'Map.Content';
+  // Enable/disable scroll wheel zoom.
+  // TODO(burdon): Use attention:
+  // const {hasAttention} = useAttention(props.id);
+  useEffect(() => {
+    if (!map) {
+      return;
+    }
+
+    if (attention) {
+      map.scrollWheelZoom.enable();
+    } else {
+      map.scrollWheelZoom.disable();
+    }
+  }, [map, attention]);
+
+  return (
+    <MapContainer
+      {...composableProps(rest, {
+        // Frame classes (formerly on Map.Root): focusable grid container.
+        classNames: 'dx-container group relative grid dx-focus-ring-inset bg-base-surface!',
+      })}
+      attributionControl={false}
+      zoomControl={false}
+      scrollWheelZoom={scrollWheelZoom}
+      doubleClickZoom={doubleClickZoom}
+      touchZoom={touchZoom}
+      // Allow fractional zoom so trackpad pinch (small ctrl+wheel deltas) isn't rounded away.
+      zoomSnap={0}
+      center={center ?? defaults.center}
+      zoom={zoom ?? defaults.zoom}
+      whenReady={whenReady}
+      ref={setMapRef}
+    >
+      <MapResize />
+      <MapPinchZoom />
+      {children}
+    </MapContainer>
+  );
+});
+
+MapViewport.displayName = 'Map.Viewport';
 
 //
 // Tiles
@@ -151,14 +275,20 @@ MapContent.displayName = 'Map.Content';
 
 const MAP_TILES_NAME = 'Map.Tiles';
 
-type MapTilesProps = {};
+/** Default OpenStreetMap raster tile template. */
+export const DEFAULT_TILE_URL = 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png';
 
-const MapTiles = (_props: MapTilesProps) => {
+type MapTilesProps = {
+  /** Leaflet tile URL template (e.g. a MapTiler style endpoint with an API key). Defaults to OpenStreetMap. */
+  url?: string;
+};
+
+const MapTiles = ({ url = DEFAULT_TILE_URL }: MapTilesProps) => {
   const ref = useRef<L.TileLayer>(null);
   const { onChange } = useMapContext(MAP_TILES_NAME);
 
   useMapEvents({
-    zoomstart: (ev) => {
+    moveend: (ev) => {
       onChange?.({
         center: ev.target.getCenter(),
         zoom: ev.target.getZoom(),
@@ -183,7 +313,7 @@ const MapTiles = (_props: MapTilesProps) => {
         data-attention={attention}
         detectRetina={true}
         className='dark:grayscale dark:invert data-[attention="0"]:!opacity-80'
-        url='https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
+        url={url}
         keepBuffer={4}
         // opacity={attention ? 1 : 0.7}
       />
@@ -217,21 +347,32 @@ MapTiles.displayName = MAP_TILES_NAME;
 
 type MapMarkersProps = {
   markers?: GeoMarker[];
+  /** Connecting lines (e.g. a route). Used here only to extend the viewport fit; drawn by `Map.Lines`. */
+  lines?: MapLine[];
   selected?: string[];
+  /** Invoked with the marker id when a marker is clicked. */
+  onSelect?: (id: string) => void;
 };
 
-const MapMarkers = ({ selected, markers }: MapMarkersProps) => {
+const MapMarkers = ({ selected, markers, lines, onSelect }: MapMarkersProps) => {
   const map = useMap();
 
-  // Set the viewport around the markers, or show the whole world map if `markers` is empty.
+  // Fit the viewport around the markers and any connecting lines. When there is nothing to frame,
+  // leave the current view alone so caller-provided center/zoom (or prior interaction) is preserved.
   useEffect(() => {
-    if (markers.length > 0) {
-      const bounds = latLngBounds(markers.map((marker) => marker.location));
-      map.fitBounds(bounds);
-    } else {
-      map.setView(defaults.center, defaults.zoom);
+    const points: LatLngLiteral[] = [
+      ...(markers?.map((marker) => marker.location) ?? []),
+      ...(lines?.flatMap((line) => [line.source, line.target]) ?? []),
+    ];
+    if (points.length > 0) {
+      const bounds = latLngBounds(points);
+      const size = map.getSize();
+      const padding = Math.max(48, Math.min(size.x, size.y) / 6);
+      // `animate: false`: a deferred zoom animation can outlive the map (e.g. on unmount) and throw
+      // a Leaflet `_leaflet_pos` error against a removed layer; fitting instantly avoids the race.
+      map.fitBounds(bounds, { padding: point(padding, padding), animate: false });
     }
-  }, [markers]);
+  }, [markers, lines, map]);
 
   return (
     <>
@@ -240,6 +381,7 @@ const MapMarkers = ({ selected, markers }: MapMarkersProps) => {
           <Marker
             key={id}
             position={{ lat, lng }}
+            eventHandlers={onSelect ? { click: () => onSelect(id) } : undefined}
             icon={
               // TODO(burdon): Create custom icon from bundled assets.
               // TODO(burdon): Selection state.
@@ -264,6 +406,46 @@ const MapMarkers = ({ selected, markers }: MapMarkersProps) => {
 
 MapMarkers.displayName = 'Map.Markers';
 
+//
+// Lines
+//
+
+/** A connecting line between two points (e.g. a route leg). `color` is any CSS/Leaflet stroke color. */
+export type MapLine = { source: LatLngLiteral; target: LatLngLiteral; color?: string };
+
+type MapLinesProps = {
+  lines?: MapLine[];
+};
+
+const MapLines = ({ lines }: MapLinesProps) => {
+  if (!lines || lines.length === 0) {
+    return null;
+  }
+
+  // Merge consecutive connected segments with the same color into a single Polyline so
+  // Leaflet renders one continuous smooth path rather than N disconnected stub segments.
+  const polylines: Array<{ positions: LatLngLiteral[]; color?: string }> = [];
+  for (const { source, target, color } of lines) {
+    const last = polylines[polylines.length - 1];
+    const lastPos = last?.positions[last.positions.length - 1];
+    if (last && last.color === color && lastPos?.lat === source.lat && lastPos?.lng === source.lng) {
+      last.positions.push(target);
+    } else {
+      polylines.push({ positions: [source, target], color });
+    }
+  }
+
+  return (
+    <>
+      {polylines.map(({ positions, color }, index) => (
+        <Polyline key={index} positions={positions} pathOptions={{ color, weight: 4, opacity: 0.8 }} />
+      ))}
+    </>
+  );
+};
+
+MapLines.displayName = 'Map.Lines';
+
 //
 // Controls
 // Integrates with Leaflet custom controls.
@@ -276,29 +458,47 @@ const CustomControl = ({
   position: ControlPosition;
 }>) => {
   const map = useMap();
+  const rootRef = useRef<ReturnType<typeof createRoot> | undefined>(undefined);
 
+  // Mount the leaflet control (and its React root) once per map/position. Children are
+  // rendered into the persistent root by the effect below, so updating them does NOT
+  // tear down and re-add the control (which would flicker on every parent re-render).
   useEffect(() => {
     const control = new Control({ position });
     control.onAdd = () => {
       const container = DomUtil.create('div', mx('m-0!', controlPositions[position]));
       DomEvent.disableClickPropagation(container);
       DomEvent.disableScrollPropagation(container);
-
       const root = createRoot(container);
+      rootRef.current = root;
+      // Initial render — covers mount and any map/position remount; the effect below
+      // handles subsequent children-only updates.
       root.render(
         <ThemeProvider tx={defaultTx}>
           <Tooltip.Provider>{children}</Tooltip.Provider>
         </ThemeProvider>,
       );
-
       return container;
     };
 
     control.addTo(map);
     return () => {
       control.remove();
+      const root = rootRef.current;
+      rootRef.current = undefined;
+      // Defer unmount so it doesn't run synchronously during a React render/commit.
+      queueMicrotask(() => root?.unmount());
     };
-  }, [map, position, children]);
+  }, [map, position]);
+
+  // Re-render children into the persistent root whenever they change.
+  useEffect(() => {
+    rootRef.current?.render(
+      <ThemeProvider tx={defaultTx}>
+        <Tooltip.Provider>{children}</Tooltip.Provider>
+      </ThemeProvider>,
+    );
+  }, [children]);
 
   return null;
 };
@@ -323,9 +523,10 @@ const MapAction = ({ onAction, position = 'bottomright', ...props }: MapControlP
 
 export const Map = {
   Root: MapRoot,
-  Content: MapContent,
+  Viewport: MapViewport,
   Tiles: MapTiles,
   Markers: MapMarkers,
+  Lines: MapLines,
   Zoom: MapZoom,
   Action: MapAction,
 };
@@ -333,8 +534,9 @@ export const Map = {
 export {
   type MapController,
   type MapRootProps,
-  type MapContentProps,
+  type MapViewportProps,
   type MapTilesProps,
   type MapMarkersProps,
+  type MapLinesProps,
   type MapControlProps,
 };

package/src/components/Toolbar/Controls.tsx

@@ -7,7 +7,7 @@ import React from 'react';
 
 import { IconButton, type ThemedClassName, Toolbar, useTranslation } from '@dxos/react-ui';
 
-import { translationKey } from '../../translations';
+import { translationKey } from '#translations';
 
 export type ControlAction = 'toggle' | 'start' | 'zoom-in' | 'zoom-out';
 

package/src/data.ts

@@ -4,6 +4,23 @@
 
 import { type Topology } from 'topojson-specification';
 
-export const loadTopology = async (): Promise<Topology> => {
-  return (await import('../data/countries-110m.ts')).default;
+/**
+ * World-atlas Natural Earth resolutions. Higher numbers = lower detail.
+ * - `110m` (~110 KB): default; suitable for low-zoom globes.
+ * - `50m`  (~750 KB): mid-zoom.
+ * - `10m`  (~3.6 MB): high zoom; pair with `useSimplifiedTopology` to keep
+ *   per-frame render cost bounded.
+ */
+export type CountriesResolution = '110m' | '50m' | '10m';
+
+export const loadTopology = async (resolution: CountriesResolution = '110m'): Promise<Topology> => {
+  switch (resolution) {
+    case '10m':
+      return (await import('../data/countries-10m.ts')).default;
+    case '50m':
+      return (await import('../data/countries-50m.ts')).default;
+    case '110m':
+    default:
+      return (await import('../data/countries-110m.ts')).default;
+  }
 };

package/src/hooks/context.tsx

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { type GeoProjection } from 'd3';
 import { type Dispatch, type SetStateAction, createContext, useContext } from 'react';
 
 import { raise } from '@dxos/debug';
@@ -21,12 +22,55 @@ export type GlobeContextType = {
   zoom: number;
   translation: Point;
   rotation: Vector;
+  setSize: Dispatch<SetStateAction<Size>>;
   setCenter: Dispatch<SetStateAction<LatLngLiteral>>;
   setZoom: Dispatch<SetStateAction<number>>;
   setTranslation: Dispatch<SetStateAction<Point>>;
   setRotation: Dispatch<SetStateAction<Vector>>;
+  /** Registers (or clears) the controller built by Globe.Canvas so Globe.Root can expose it via its ref. */
+  registerController: (controller: GlobeController | null) => void;
 };
 
+//
+// Controller
+//
+
+/**
+ * Imperative options accepted by GlobeController.flyTo.
+ */
+export type FlyToOptions = {
+  /** Base duration in ms (scales with great-circle distance). */
+  duration?: number;
+  /** Optional pitch offset applied along the latitude axis of the target. */
+  tilt?: number;
+  /**
+   * Optional per-frame callback fired before the rotation tween advances.
+   * Useful for layered animations (e.g. cursor / arc trails in tours).
+   * `t` runs 0→1 across the eased duration.
+   */
+  onTick?: (t: number) => void;
+};
+
+export type FlyToTarget = LatLngLiteral & {
+  /** Optional zoom factor; interpolated alongside rotation when set. */
+  zoom?: number;
+};
+
+export type GlobeController = {
+  canvas: HTMLCanvasElement;
+  projection: GeoProjection;
+  /**
+   * Animates the globe to the given lat/lng (and optional zoom) along a
+   * great-circle arc. Returns a Promise that resolves on completion and
+   * rejects if interrupted (e.g. by another flyTo on the same globe).
+   */
+  flyTo: (target: FlyToTarget, options?: FlyToOptions) => Promise<void>;
+  /**
+   * Interrupts any in-flight `flyTo` (used by tours when stopped mid-segment).
+   */
+  cancelFlyTo: () => void;
+} & Pick<GlobeContextType, 'zoom' | 'translation' | 'rotation' | 'setZoom' | 'setTranslation' | 'setRotation'>;
+
 /** @internal */
 // TODO(burdon): Replace with radix.
 export const GlobeContext = createContext<GlobeContextType>(undefined);

package/src/hooks/index.ts

@@ -6,5 +6,8 @@ export * from './context';
 export * from './useDrag';
 export * from './useGlobeZoomHandler';
 export * from './useMapZoomHandler';
+export * from './useSimplifiedTopology';
 export * from './useSpinner';
+export * from './useTopology';
 export * from './useTour';
+export * from './useWheel';