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

package/src/hooks/useDrag.ts

@@ -5,8 +5,8 @@
 import { select } from 'd3';
 import { useEffect } from 'react';
 
-import { type GlobeController } from '../components';
 import { geoInertiaDrag } from '../util';
+import { type GlobeController } from './context';
 
 export type GlobeDragEvent = {
   type: 'start' | 'move' | 'end';
@@ -16,7 +16,27 @@ export type GlobeDragEvent = {
 export type DragOptions = {
   disabled?: boolean;
   duration?: number;
-  xAxis?: boolean; // TODO(burdon): Generalize.
+  /**
+   * When true, drag is constrained to rotation around the polar (vertical)
+   * axis only — i.e. longitude changes freely but the camera's tilt
+   * (latitude / phi) stays pinned at whatever value the root's `rotation`
+   * prop was initialised with. Useful for "earth-spinning-at-an-angle"
+   * presentations where the inclination should not change.
+   */
+  lockTilt?: boolean;
+  /**
+   * Drag rotation mode:
+   * - `linear` (default): direct pixel-to-Euler mapping (Δx → lambda,
+   *   Δy → phi, gamma fixed at 0). Rotation is constrained to two axes;
+   *   no roll. The dragged point does not track the cursor exactly.
+   * - `versor`: quaternion-based rotation so that the dragged point
+   *   follows the cursor exactly. May induce roll (gamma).
+   */
+  mode?: 'linear' | 'versor';
+  /**
+   * Degrees of rotation per pixel of drag, in linear mode. Default 0.25.
+   */
+  sensitivity?: number;
   onUpdate?: (event: GlobeDragEvent) => void;
 };
 
@@ -30,7 +50,7 @@ export const useDrag = (controller?: GlobeController | null, options: DragOption
       return;
     }
 
-    geoInertiaDrag(
+    const inertia = geoInertiaDrag(
       select(canvas),
       () => {
         controller.setRotation(controller.projection.rotate());
@@ -38,16 +58,24 @@ export const useDrag = (controller?: GlobeController | null, options: DragOption
       },
       controller.projection,
       {
-        xAxis: options.xAxis,
+        lockTilt: options.lockTilt,
+        mode: options.mode,
+        sensitivity: options.sensitivity,
+        // Zoom-driven gain: matches useWheel — degrees-per-pixel shrinks as the
+        // globe gets larger on screen so the drag feel is consistent across zoom.
+        getZoom: () => controller.zoom,
         time: 3_000,
         start: () => options.onUpdate?.({ type: 'start', controller }),
         finish: () => options.onUpdate?.({ type: 'end', controller }),
       },
     );
 
-    // TODO(burdon): Cancel drag timer.
     return () => {
       cancelDrag(select(canvas));
+      // Stop any in-flight inertia: otherwise its d3-timer keeps writing
+      // through the (stable) setRotation closure into the live React state,
+      // even after this effect has been replaced.
+      inertia?.timer?.stop();
     };
   }, [controller, JSON.stringify(options)]);
 };

package/src/hooks/useGlobeZoomHandler.ts

@@ -4,7 +4,8 @@
 
 import { useCallback } from 'react';
 
-import { type ControlProps, type GlobeController } from '../components';
+import { type ControlProps } from '../components';
+import { type GlobeController } from './context';
 
 const ZOOM_FACTOR = 0.1;
 

package/src/hooks/useSimplifiedTopology.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useMemo } from 'react';
+import { presimplify, quantile, simplify } from 'topojson-simplify';
+import { type Topology } from 'topojson-specification';
+
+/**
+ * Zoom → minWeight policy. The default thresholds were chosen empirically
+ * against the 10m world-atlas dataset: each tier targets a percentile of
+ * removable points so that the per-frame d3-geo path cost stays roughly
+ * constant as the user zooms in.
+ */
+export type SimplifyTier = {
+  /** Lower bound (inclusive) of the zoom range this tier applies to. */
+  minZoom: number;
+  /** Percentile in [0, 1] passed to `topojson.quantile`. 1 = keep no points; 0 = keep all. */
+  percentile: number;
+};
+
+const DEFAULT_TIERS: SimplifyTier[] = [
+  { minZoom: 0, percentile: 0.95 },
+  { minZoom: 2, percentile: 0.85 },
+  { minZoom: 4, percentile: 0.6 },
+  { minZoom: 7, percentile: 0.3 },
+  { minZoom: 12, percentile: 0 },
+];
+
+const pickTier = (zoom: number, tiers: SimplifyTier[]): SimplifyTier => {
+  let match = tiers[0];
+  for (const tier of tiers) {
+    if (zoom >= tier.minZoom) {
+      match = tier;
+    }
+  }
+  return match;
+};
+
+export type UseSimplifiedTopologyOptions = {
+  /**
+   * Zoom buckets that map a zoom value to a simplification percentile. The
+   * hook picks the highest-`minZoom` tier whose bound is ≤ the current zoom,
+   * so tiers may be listed in any order but ascending is conventional.
+   */
+  tiers?: SimplifyTier[];
+};
+
+/**
+ * Returns a simplified copy of `topology` whose detail tracks the current
+ * `zoom`. The source topology is annotated with point weights once via
+ * `presimplify`; subsequent zoom changes reuse that work and only re-run
+ * the cheap `simplify` pass against a tier-bucketed `minWeight`.
+ *
+ * Pass the highest-resolution source you have (typically `10m`) and let the
+ * hook decimate at low zoom — that's the cheap end of the curve.
+ */
+export const useSimplifiedTopology = (
+  topology: Topology | undefined,
+  zoom: number,
+  options: UseSimplifiedTopologyOptions = {},
+): Topology | undefined => {
+  const { tiers = DEFAULT_TIERS } = options;
+
+  // One-shot weight annotation per source topology.
+  const presimplified = useMemo(() => (topology ? presimplify(topology) : undefined), [topology]);
+
+  // Stable per-tier quantile lookup so identical zoom buckets do not retrigger.
+  const tier = pickTier(zoom, tiers);
+
+  return useMemo(() => {
+    if (!presimplified) {
+      return undefined;
+    }
+    if (tier.percentile <= 0) {
+      return presimplified;
+    }
+    const minWeight = quantile(presimplified, tier.percentile);
+    return simplify(presimplified, minWeight);
+  }, [presimplified, tier]);
+};

package/src/hooks/useSpinner.ts

@@ -6,7 +6,7 @@ import { timer as d3Timer } from 'd3';
 import { type Timer } from 'd3';
 import { useEffect, useState } from 'react';
 
-import { type GlobeController } from '../components';
+import { type GlobeController } from './context';
 import { type Vector } from './context';
 
 export type SpinnerOptions = {

package/src/hooks/useTopology.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+import { type Topology } from 'topojson-specification';
+
+import { log } from '@dxos/log';
+
+import { type CountriesResolution, loadTopology } from '../data';
+
+export type Level = CountriesResolution;
+
+export type LevelTier = {
+  /** Lower bound (inclusive) of the zoom range. */
+  minZoom: number;
+  /** Topology resolution to load when this tier is active. */
+  level: CountriesResolution;
+};
+
+/** Default zoom buckets: 110m below zoom 3, 50m at zoom 3 and above. */
+const DEFAULT_TIERS: LevelTier[] = [
+  { minZoom: 0, level: '110m' },
+  // TODO(burdon): Too slow.
+  // { minZoom: 3, level: '50m' },
+  // { minZoom: 6, level: '10m' },
+];
+
+const pickTier = (zoom: number, tiers: LevelTier[]): LevelTier => {
+  let match = tiers[0];
+  for (const tier of tiers) {
+    if (zoom >= tier.minZoom) {
+      match = tier;
+    }
+  }
+
+  return match;
+};
+
+export type UseTopologyOptions = {
+  /** Zoom buckets that map a zoom value to a resolution. Default: 110m / 50m at 0 / 3. */
+  tiers?: LevelTier[];
+};
+
+// Previously-loaded topologies are kept in a module-level cache so re-crossing a tier boundary
+// doesn't re-fetch/re-parse the file.
+const topologyCache = new Map<CountriesResolution, Topology>();
+
+/**
+ * Loads TopoJSON country data.
+ *
+ * - With no arguments, loads the default `110m` resolution.
+ * - With a `zoom`, loads the resolution matching the current zoom tier (progressive level-of-detail).
+ *   Each resolution is a separate dynamic `import()`, so unused detail levels are never fetched, and
+ *   while a heavier tier loads the previously-displayed topology stays on screen (no blank canvas).
+ */
+export const useTopology: {
+  (): Topology | undefined;
+  (zoom: number, options?: UseTopologyOptions): Topology | undefined;
+} = (zoom?: number, options: UseTopologyOptions = {}): Topology | undefined => {
+  const { tiers = DEFAULT_TIERS } = options;
+  const level: CountriesResolution = zoom === undefined ? '110m' : pickTier(zoom, tiers).level;
+
+  const [topology, setTopology] = useState<Topology | undefined>(() => topologyCache.get(level));
+
+  useEffect(() => {
+    const cached = topologyCache.get(level);
+    if (cached) {
+      setTopology(cached);
+      return;
+    }
+
+    let disposed = false;
+    void loadTopology(level)
+      .then((loaded) => {
+        topologyCache.set(level, loaded);
+        if (!disposed) {
+          setTopology(loaded);
+        }
+      })
+      .catch((err) => {
+        // A chunk/network failure leaves the previously-displayed topology on screen; log rather
+        // than surfacing an unhandled rejection.
+        if (!disposed) {
+          log.warn('failed to load topology', { level, err });
+        }
+      });
+
+    return () => {
+      disposed = true;
+    };
+  }, [level]);
+
+  return topology;
+};

package/src/hooks/useTour.ts

@@ -2,15 +2,12 @@
 // Copyright 2024 DXOS.org
 //
 
-import { selection as d3Selection, geoDistance, geoInterpolate, geoPath } from 'd3';
-import { type Dispatch, type SetStateAction, useEffect, useMemo, useState } from 'react';
-import versor from 'versor';
+import { geoInterpolate, geoPath } from 'd3';
+import { type Dispatch, type SetStateAction, useEffect, useState } from 'react';
 
-import type { GlobeController } from '../components';
 import { type LatLngLiteral } from '../types';
-import { type StyleSet, geoToPosition, positionToRotation } from '../util';
-
-const TRANSITION_NAME = 'globe-tour';
+import { type StyleSet, geoToPosition } from '../util';
+import type { GlobeController } from './context';
 
 const defaultDuration = 1_500;
 
@@ -25,7 +22,8 @@ export type TourOptions = {
 };
 
 /**
- * Iterates between points.
+ * Iterates between points by chaining `controller.flyTo` calls, rendering
+ * an arc + cursor on the canvas per frame via the flyTo `onTick` hook.
  * Inspired by: https://observablehq.com/@mbostock/top-100-cities
  */
 export const useTour = (
@@ -33,91 +31,82 @@ export const useTour = (
   points?: LatLngLiteral[],
   options: TourOptions = {},
 ): [boolean, Dispatch<SetStateAction<boolean>>] => {
-  const selection = useMemo(() => d3Selection(), []);
   // TODO(burdon): Redo controlled state.
   const [running, setRunning] = useState(options.running ?? false);
   useEffect(() => {
-    if (!running) {
-      selection.interrupt(TRANSITION_NAME);
+    if (!controller || !running) {
       return;
     }
 
-    let t: ReturnType<typeof setTimeout>;
-    if (controller && running) {
-      t = setTimeout(async () => {
-        const { canvas, projection, setRotation } = controller;
-        const context = canvas.getContext('2d', { alpha: false });
-        const path = geoPath(projection, context).pointRadius(2);
+    let cancelled = false;
+    const t = setTimeout(async () => {
+      const { canvas, projection } = controller;
+      const context = canvas.getContext('2d', { alpha: false });
+      const path = geoPath(projection, context).pointRadius(2);
+
+      try {
+        const tourPoints = [...points];
+        if (options.loop) {
+          tourPoints.push(tourPoints[0]);
+        }
 
-        const tilt = options.tilt ?? 0;
-        let last: LatLngLiteral;
-        try {
-          const p = [...points];
-          if (options.loop) {
-            p.push(p[0]);
+        let last: LatLngLiteral | undefined;
+        for (const next of tourPoints) {
+          if (cancelled) {
+            break;
           }
 
-          for (const next of p) {
-            if (!running) {
-              break;
+          const p1 = last ? geoToPosition(last) : undefined;
+          const p2 = geoToPosition(next);
+          const ip = geoInterpolate(p1 ?? p2, p2);
+
+          // Cursor + trailing arc render per frame. Must run before the
+          // rotation tween advances the projection — flyTo registers
+          // `onTick` before its rotation tween, preserving this ordering.
+          const onTick = (t: number) => {
+            const t1 = Math.max(0, Math.min(1, t * 2 - 1));
+            const t2 = Math.min(1, t * 2);
+
+            context.save();
+            try {
+              context.beginPath();
+              context.strokeStyle = options.styles?.arc?.strokeStyle ?? 'yellow';
+              context.lineWidth = (options.styles?.arc?.lineWidth ?? 1.5) * (controller.zoom ?? 1);
+              context.setLineDash(options.styles?.arc?.lineDash ?? []);
+              path({ type: 'LineString', coordinates: [ip(t1), ip(t2)] });
+              context.stroke();
+
+              context.beginPath();
+              context.fillStyle = options.styles?.cursor?.fillStyle ?? 'orange';
+              path.pointRadius((options.styles?.cursor?.pointRadius ?? 2) * (controller.zoom ?? 1));
+              path({ type: 'Point', coordinates: ip(t2) });
+              context.fill();
+            } finally {
+              context.restore();
             }
-
-            // Points.
-            const p1 = last ? geoToPosition(last) : undefined;
-            const p2 = geoToPosition(next);
-            const ip = geoInterpolate(p1 || p2, p2);
-            const distance = geoDistance(p1 || p2, p2);
-
-            // Rotation.
-            const r1 = p1 ? positionToRotation(p1, tilt) : controller.projection.rotate();
-            const r2 = positionToRotation(p2, tilt);
-            const iv = versor.interpolate(r1, r2);
-
-            const transition = selection
-              .transition(TRANSITION_NAME)
-              .duration(Math.max(options.duration ?? defaultDuration, distance * 2_000))
-              .tween('render', () => (t) => {
-                const t1 = Math.max(0, Math.min(1, t * 2 - 1));
-                const t2 = Math.min(1, t * 2);
-
-                context.save();
-                {
-                  context.beginPath();
-                  context.strokeStyle = options?.styles?.arc?.strokeStyle ?? 'yellow';
-                  context.lineWidth = (options?.styles?.arc?.lineWidth ?? 1.5) * (controller?.zoom ?? 1);
-                  context.setLineDash(options?.styles?.arc?.lineDash ?? []);
-                  path({ type: 'LineString', coordinates: [ip(t1), ip(t2)] });
-                  context.stroke();
-
-                  context.beginPath();
-                  context.fillStyle = options?.styles?.cursor?.fillStyle ?? 'orange';
-                  path.pointRadius((options?.styles?.cursor?.pointRadius ?? 2) * (controller?.zoom ?? 1));
-                  path({ type: 'Point', coordinates: ip(t2) });
-                  context.fill();
-                }
-                context.restore();
-
-                // TODO(burdon): This has to come after rendering above. Add to features to correct order?
-                projection.rotate(iv(t));
-                setRotation(projection.rotate());
-              });
-
-            // Throws if interrupted.
-            await transition.end();
-            last = next;
-          }
-        } catch {
-          // Ignore.
-        } finally {
+          };
+
+          await controller.flyTo(next, {
+            duration: options.duration ?? defaultDuration,
+            tilt: options.tilt ?? 0,
+            onTick,
+          });
+          last = next;
+        }
+      } catch {
+        // Interrupted (e.g. external flyTo or tour stopped).
+      } finally {
+        if (!cancelled) {
           setRunning(false);
         }
-      });
-
-      return () => {
-        clearTimeout(t);
-        selection.interrupt(TRANSITION_NAME);
-      };
-    }
+      }
+    });
+
+    return () => {
+      cancelled = true;
+      clearTimeout(t);
+      controller.cancelFlyTo();
+    };
   }, [controller, running, JSON.stringify(options)]);
 
   return [running, setRunning];

package/src/hooks/useWheel.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect } from 'react';
+
+import { type GlobeController } from './context';
+import { type Vector } from './context';
+
+export type WheelOptions = {
+  disabled?: boolean;
+  /**
+   * Degrees of rotation per pixel of wheel delta (non-zoom gestures).
+   */
+  sensitivity?: number;
+  /**
+   * Zoom factor per pixel of pinch / ctrl+scroll delta. Applied exponentially
+   * so equal pinch-in / pinch-out deltas cancel exactly. Default 0.01.
+   */
+  zoomSensitivity?: number;
+  onUpdate?: (controller: GlobeController) => void;
+};
+
+const DEFAULT_SENSITIVITY = 0.25;
+const DEFAULT_ZOOM_SENSITIVITY = 0.01;
+
+/**
+ * Map mouse-wheel / trackpad gestures to globe motion:
+ * - Scroll (or two-finger pan on a trackpad) rotates the globe:
+ *   deltaY → phi (tilt around screen-X), deltaX → lambda (polar spin).
+ * - Pinch-to-zoom on a trackpad — and ctrl+scroll on a mouse — are
+ *   delivered as `wheel` events with `ctrlKey: true`. Those are routed
+ *   to `setZoom` instead so the gesture matches the user's intent.
+ */
+export const useWheel = (controller?: GlobeController | null, options: WheelOptions = {}) => {
+  useEffect(() => {
+    const canvas = controller?.canvas;
+    if (!canvas || options.disabled) {
+      return;
+    }
+
+    const sensitivity = options.sensitivity ?? DEFAULT_SENSITIVITY;
+    const zoomSensitivity = options.zoomSensitivity ?? DEFAULT_ZOOM_SENSITIVITY;
+
+    const handleWheel = (event: WheelEvent) => {
+      event.preventDefault();
+      if (event.ctrlKey) {
+        // Pinch-to-zoom on trackpads, or ctrl+scroll on a mouse. The
+        // browser synthesises ctrlKey on pinch even when ctrl is not held.
+        // Read live zoom from controller.zoom (a getter on zoomRef.current)
+        // and set the new value directly: useControlledState's functional
+        // setter resolves against the prop, not the state, and passing a
+        // function to controller.setZoom triggers the 200ms eased transition
+        // intended for button clicks.
+        const factor = Math.exp(-event.deltaY * zoomSensitivity);
+        controller.setZoom(controller.zoom * factor);
+      } else {
+        // Read the live rotation off the projection (kept in sync by the
+        // render effect). The React-state path can't be used here:
+        // - `controller.rotation` is a snapshot captured by useImperativeHandle.
+        // - `useControlledState`'s functional setter resolves `prev` against
+        //   the latest *prop*, not the latest state, so each event would
+        //   start from the initial rotation and just jitter around it.
+        // Mutating the projection here matches how useDrag accumulates.
+        // Both deltas are negated so the wheel feels like "natural scroll":
+        // scrolling/swiping in a direction moves the globe content the same way.
+        // Scale by 1/zoom so the gesture feels consistent at any zoom level
+        // (a bigger on-screen globe needs smaller angular rotation per pixel).
+        const [lambda, phi, gamma] = controller.projection.rotate() as Vector;
+        const k = sensitivity / Math.max(controller.zoom, 0.1);
+        const next: Vector = [lambda - event.deltaX * k, phi + event.deltaY * k, gamma];
+        controller.projection.rotate(next);
+        controller.setRotation(controller.projection.rotate() as Vector);
+      }
+      options.onUpdate?.(controller);
+    };
+
+    canvas.addEventListener('wheel', handleWheel, { passive: false });
+    return () => {
+      canvas.removeEventListener('wheel', handleWheel);
+    };
+  }, [controller, options.disabled, options.sensitivity, options.zoomSensitivity, options.onUpdate]);
+};

package/src/index.ts

@@ -3,8 +3,6 @@
 //
 
 export * from './components';
-export * from './data';
 export * from './hooks';
-export * from './translations';
 export type * from './types';
 export * from './util';

package/src/util/animation.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type GeoProjection, geoDistance } from 'd3';
+import versor from 'versor';
+
+import { type Vector } from '../hooks/context';
+
+/**
+ * Duration scaled by great-circle distance between two geo positions.
+ * Ensures long jumps animate longer than short ones while clamping to a
+ * minimum base. `scale` controls how steeply duration grows with distance
+ * (ms per radian of arc).
+ */
+export const flyDuration = (p1: [number, number], p2: [number, number], base: number, scale: number): number =>
+  Math.max(base, geoDistance(p1, p2) * scale);
+
+/**
+ * Per-frame tween that interpolates the projection's rotation between two
+ * Euler triples along the shortest great-circle arc using versors. Mutates
+ * the projection and pushes the normalised rotation through `setRotation`.
+ */
+export const createRotationTween = (
+  projection: GeoProjection,
+  setRotation: (rotation: Vector) => void,
+  r1: Vector,
+  r2: Vector,
+): ((t: number) => void) => {
+  const iv = versor.interpolate(r1, r2);
+  return (t: number) => {
+    projection.rotate(iv(t));
+    setRotation(projection.rotate() as Vector);
+  };
+};

package/src/util/index.ts

@@ -2,7 +2,9 @@
 // Copyright 2019 DXOS.org
 //
 
+export * from './animation';
 export * from './debug';
 export * from './inertia';
 export * from './path';
 export * from './render';
+export * from './styles';