@dxos/react-ui-geo 0.7.5-labs.35b4b42

package/src/hooks/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './context';
+export * from './useDrag';
+export * from './useGlobeZoomHandler';
+export * from './useMapZoomHandler';
+export * from './useSpinner';
+export * from './useTour';

package/src/hooks/useDrag.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as d3 from 'd3';
+import { useEffect } from 'react';
+
+import { type GlobeController } from '../components';
+import { geoInertiaDrag } from '../util';
+
+export type GlobeDragEvent = {
+  type: 'start' | 'move' | 'end';
+  controller: GlobeController;
+};
+
+export type DragOptions = {
+  disabled?: boolean;
+  duration?: number;
+  xAxis?: boolean; // TODO(burdon): Generalize.
+  onUpdate?: (event: GlobeDragEvent) => void;
+};
+
+/**
+ * Allows user to drag globe.
+ */
+export const useDrag = (controller?: GlobeController | null, options: DragOptions = {}) => {
+  useEffect(() => {
+    const canvas = controller?.canvas;
+    if (!canvas || options.disabled) {
+      return;
+    }
+
+    geoInertiaDrag(
+      d3.select(canvas),
+      () => {
+        controller.setRotation(controller.projection.rotate());
+        options.onUpdate?.({ type: 'move', controller });
+      },
+      controller.projection,
+      {
+        xAxis: options.xAxis,
+        time: 3_000,
+        start: () => options.onUpdate?.({ type: 'start', controller }),
+        finish: () => options.onUpdate?.({ type: 'end', controller }),
+      },
+    );
+
+    // TODO(burdon): Cancel drag timer.
+    return () => {
+      cancelDrag(d3.select(canvas));
+    };
+  }, [controller, options]);
+};
+
+const cancelDrag = (node) => node.on('.drag', null);

package/src/hooks/useGlobeZoomHandler.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCallback } from 'react';
+
+import { type GlobeController, type ControlProps } from '../components';
+
+export const useGlobeZoomHandler = (controller: GlobeController | null | undefined): ControlProps['onAction'] => {
+  return useCallback<ControlProps['onAction']>(
+    (event) => {
+      if (!controller) {
+        return;
+      }
+
+      switch (event) {
+        case 'zoom-in': {
+          controller.setScale((scale) => scale * 1.1);
+          break;
+        }
+        case 'zoom-out': {
+          controller.setScale((scale) => scale * 0.9);
+          break;
+        }
+      }
+    },
+    [controller],
+  );
+};

package/src/hooks/useMapZoomHandler.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCallback } from 'react';
+
+import { type MapController, type ControlProps } from '../components';
+
+export const useMapZoomHandler = (controller: MapController | null | undefined): ControlProps['onAction'] => {
+  return useCallback<ControlProps['onAction']>(
+    (event) => {
+      if (!controller) {
+        return;
+      }
+
+      switch (event) {
+        case 'zoom-in': {
+          controller.setZoom((scale) => scale + 1);
+          break;
+        }
+        case 'zoom-out': {
+          controller.setZoom((scale) => scale - 1);
+          break;
+        }
+      }
+    },
+    [controller],
+  );
+};

package/src/hooks/useSpinner.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as d3 from 'd3';
+import { type Timer } from 'd3';
+import { useEffect, useState } from 'react';
+
+import { type Vector } from './context';
+import { type GlobeController } from '../components';
+
+export type SpinnerOptions = {
+  disabled?: boolean;
+  delta?: Vector;
+};
+
+/**
+ * Rotates globe.
+ */
+export const useSpinner = (controller?: GlobeController | null, options: SpinnerOptions = {}) => {
+  const [running, setRunning] = useState(false);
+  useEffect(() => {
+    let timer: Timer | undefined;
+
+    const start = () => {
+      const delta: Vector = options.delta ?? [0.001, 0, 0];
+
+      let t = 0;
+      let lastRotation = controller.projection.rotate();
+      timer = d3.timer((elapsed) => {
+        const dt = elapsed - t;
+        t = elapsed;
+
+        const rotation: Vector = [
+          lastRotation[0] + delta[0] * dt,
+          lastRotation[1] + delta[1] * dt,
+          lastRotation[2] + delta[2] * dt,
+        ];
+
+        lastRotation = rotation;
+        controller.setRotation(rotation);
+      });
+    };
+
+    const stop = () => {
+      if (timer) {
+        timer.stop();
+        timer = undefined;
+      }
+    };
+
+    if (controller && running) {
+      start();
+    } else {
+      stop();
+    }
+
+    return () => stop();
+  }, [controller, running]);
+
+  return [
+    () => {
+      if (!options.disabled) {
+        setRunning(true);
+      }
+    },
+    () => setRunning(false),
+  ];
+};

package/src/hooks/useTour.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as d3 from 'd3';
+import { useEffect, useState } from 'react';
+import versor from 'versor';
+
+import type { GlobeController } from '../components';
+import { type Features, geoToPosition, type LatLng, positionToRotation, type StyleSet } from '../util';
+
+const TRANSITION_NAME = 'globe-tour';
+
+const defaultDuration = 1_500;
+
+export type TourOptions = {
+  disabled?: boolean;
+  styles?: StyleSet;
+  duration?: number;
+};
+
+/**
+ * Iterates between points.
+ * Inspired by: https://observablehq.com/@mbostock/top-100-cities
+ */
+export const useTour = (controller?: GlobeController | null, features?: Features, options: TourOptions = {}) => {
+  const selection = d3.selection();
+  const [running, setRunning] = useState(false);
+  useEffect(() => {
+    if (!running) {
+      selection.interrupt(TRANSITION_NAME);
+      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 = d3.geoPath(projection, context).pointRadius(2);
+
+        const tilt = 0;
+        let last: LatLng;
+        try {
+          for (const next of features.points) {
+            if (!running) {
+              break;
+            }
+
+            // Points.
+            const p1 = last ? geoToPosition(last) : undefined;
+            const p2 = geoToPosition(next);
+            const ip = d3.geoInterpolate(p1 || p2, p2);
+            const distance = d3.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?.scale ?? 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?.scale ?? 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 (err) {
+          setRunning(false);
+        }
+      });
+
+      return () => {
+        clearTimeout(t);
+        selection.interrupt(TRANSITION_NAME);
+      };
+    }
+  }, [controller, running]);
+
+  return [
+    () => {
+      if (!options.disabled) {
+        setRunning(true);
+      }
+    },
+    () => setRunning(false),
+  ];
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2019 DXOS.org
+//
+
+export * from './components';
+export * from './data';
+export * from './hooks';
+export * from './types';
+export * from './util';

package/src/types.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type LatLngLiteral } from 'leaflet';
+
+export type MapMarker = {
+  id: string;
+  title?: string;
+  location: LatLngLiteral;
+};

package/src/util/debug.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+const debug = false;
+
+export const timer = <T = void>(cb: () => T): T => {
+  const start = Date.now();
+  const data = cb();
+  const t = Date.now() - start / 1_000;
+  if (debug) {
+    // eslint-disable-next-line no-console
+    console.log({ t, data });
+  }
+  return data;
+};

package/src/util/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2019 DXOS.org
+//
+
+export * from './debug';
+export * from './inertia';
+export * from './path';
+export * from './render';

package/src/util/inertia.ts

@@ -0,0 +1,197 @@
+//
+// Copyright 2017 Philippe Rivière
+// Copyright 2024 DXOS.org
+// https://github.com/Fil/d3-inertia
+//
+
+import * as d3 from 'd3';
+import versor from 'versor';
+
+export const restrictAxis =
+  (axis: boolean[]) =>
+  (original: number[], current: number[]): number[] =>
+    current.map((d, i) => (axis[i] ? d : original[i]));
+
+/**
+ * Applies a drag handler to the specified target element.
+ */
+// TODO(burdon): Define type.
+export const geoInertiaDrag = (target, render, projection, options) => {
+  if (!options) {
+    options = {};
+  }
+
+  // Target can be an element, a selector, a function, or a selection
+  // but in case of a selection we make sure to reselect it with d3-selection.
+  if (target.node) {
+    target = target.node();
+  }
+  target = d3.select(target);
+
+  // Complete params: (projection, render, startDrag, dragging, endDrag).
+  const inertia = geoInertiaDragHelper({
+    projection,
+    render: (rotation) => {
+      projection.rotate(rotation);
+      render && render();
+    },
+    axis: restrictAxis(options.xAxis ? [true, false, false] : [true, true, true]),
+    start: options.start,
+    move: options.move,
+    end: options.end,
+    stop: options.stop,
+    finish: options.finish,
+    time: options.time,
+    hold: options.hold,
+  });
+
+  target.call(d3.drag().on('start', inertia.start).on('drag', inertia.move).on('end', inertia.end));
+  return inertia;
+};
+
+/**
+ * A versor is a compact way to describe a rotation in 3D space.
+ * It consists of four components [𝑤,x,y,z], where:
+ * 𝑤 is a scalar representing the angle of rotation.
+ * x, y, z are the vector components, representing the axis of rotation.
+ */
+const geoInertiaDragHelper = (opt) => {
+  const projection = opt.projection;
+
+  let v0; // Mouse position in Cartesian coordinates at start of drag gesture.
+  let r0; // Projection rotation as Euler angles at start.
+  let q0; // Projection rotation as versor at start.
+  let v10; // Mouse position in Cartesian coordinates just before end of drag gesture.
+  let v11; // Mouse position in Cartesian coordinates at end.
+  let q10; // Projection rotation as versor at end.
+
+  const inertia = inertiaHelper({
+    axis: opt.axis,
+
+    start: () => {
+      v0 = versor.cartesian(projection.invert(inertia.position));
+      r0 = projection.rotate();
+      q0 = versor(r0);
+      opt.start && opt.start();
+    },
+
+    move: () => {
+      const inv = projection.rotate(r0).invert(inertia.position);
+      if (isNaN(inv[0])) {
+        return;
+      }
+      const v1 = versor.cartesian(inv);
+      const q1 = versor.multiply(q0, versor.delta(v0, v1));
+      const r1 = versor.rotation(q1);
+      const r2 = opt.axis(r0, r1);
+      opt.render(r2);
+      opt.move && opt.move();
+    },
+
+    end: () => {
+      // Velocity.
+      v10 = versor.cartesian(projection.invert(inertia.position.map((d, i) => d - inertia.velocity[i] / 1_000)));
+      q10 = versor(projection.rotate());
+      v11 = versor.cartesian(projection.invert(inertia.position));
+      opt.end && opt.end();
+    },
+
+    stop: opt.stop,
+
+    finish: opt.finish,
+
+    render: (t) => {
+      const r1 = versor.rotation(versor.multiply(q10, versor.delta(v10, v11, t * 1_000)));
+      const r2 = opt.axis(r0, r1);
+      opt.render && opt.render(r2);
+    },
+
+    time: opt.time,
+  });
+
+  return inertia;
+};
+
+function inertiaHelper(opt) {
+  const A = opt.time || 5_000; // Reference time in ms.
+  const limit = 1.0001;
+  const B = -Math.log(1 - 1 / limit);
+  const inertia = {
+    position: [0, 0],
+    velocity: [0, 0], // Velocity in pixels/s.
+    timer: d3.timer(() => {}),
+    time: 0,
+    t: 0,
+
+    start: function (ev) {
+      const position = [ev.x, ev.y];
+      inertia.position = position;
+      inertia.velocity = [0, 0];
+      inertia.timer.stop();
+      this.classList.remove('inertia');
+      this.classList.add('dragging');
+      opt.start && opt.start.call(this, position);
+    },
+
+    move: function (ev) {
+      const position = [ev.x, ev.y];
+
+      const time = performance.now();
+      const deltaTime = time - inertia.time;
+      const decay = 1 - Math.exp(-deltaTime / 1_000);
+      inertia.velocity = inertia.velocity.map((d, i) => {
+        const deltaPos = position[i] - inertia.position[i];
+        const deltaTime = time - inertia.time;
+        return (1_000 * (1 - decay) * deltaPos) / deltaTime + d * decay;
+      });
+
+      // Clamp velocity axis.
+      inertia.velocity = opt.axis([0, 0], inertia.velocity);
+
+      inertia.time = time;
+      inertia.position = position;
+      opt.move && opt.move.call(this, position);
+    },
+
+    end: function (ev) {
+      this.classList.remove('dragging', 'inertia');
+
+      const v = inertia.velocity;
+      if (v[0] * v[0] + v[1] * v[1] < 100) {
+        inertia.timer.stop();
+        return opt.stop && opt.stop();
+      }
+
+      const time = performance.now();
+      const deltaTime = time - inertia.time;
+
+      if (opt.hold === undefined) {
+        opt.hold = 100;
+      } // Default flick->drag threshold time (0 disables inertia).
+
+      if (deltaTime >= opt.hold) {
+        inertia.timer.stop();
+        return opt.stop && opt.stop();
+      }
+
+      this.classList.add('inertia');
+      opt.end && opt.end();
+
+      const self = this;
+      inertia.timer.restart((e) => {
+        inertia.t = limit * (1 - Math.exp((-B * e) / A));
+        opt.render && opt.render(inertia.t);
+        if (inertia.t > 1) {
+          inertia.timer.stop();
+          self.classList.remove('inertia');
+          inertia.velocity = [0, 0];
+          inertia.t = 1;
+          opt.finish && opt.finish();
+        }
+      });
+    },
+  };
+
+  inertia.timer.stop();
+  return inertia;
+}

package/src/util/path.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import * as d3 from 'd3';
+import { type GeoGeometryObjects } from 'd3';
+import { type Point, type Polygon, type Position } from 'geojson';
+
+import type { Vector } from '../hooks';
+
+export type LatLng = { lat: number; lng: number };
+
+// TODO(burdon): Clean-up.
+
+export const positionToRotation = ([lng, lat]: [number, number], tilt = 0): Vector => [-lng, tilt - lat, 0];
+
+export const geoToPosition = ({ lat, lng }: LatLng): [number, number] => [lng, lat];
+
+export const geoPoint = (point: LatLng): Point => ({ type: 'Point', coordinates: geoToPosition(point) });
+
+// https://github.com/d3/d3-geo#geoCircle
+export const geoCircle = ({ lat, lng }: LatLng, radius: number): Polygon =>
+  d3.geoCircle().radius(radius).center([lng, lat])();
+
+export const geoLine = (p1: LatLng, p2: LatLng): GeoGeometryObjects => ({
+  type: 'LineString',
+  coordinates: [
+    [p1.lng, p1.lat],
+    [p2.lng, p2.lat],
+  ],
+});
+
+export const closestPoint = (points: Position[], target: Position): Position | null => {
+  if (points.length === 0) {
+    return target;
+  }
+
+  let closestPoint = points[0];
+  let minDistance = getDistance(points[0], target);
+
+  for (const point of points) {
+    const distance = getDistance(point, target);
+    if (distance < minDistance) {
+      minDistance = distance;
+      closestPoint = point;
+    }
+  }
+
+  return closestPoint;
+};
+
+export const getDistance = (point1: Position, point2: Position): number => {
+  const dx = point1[0] - point2[0];
+  const dy = point1[1] - point2[1];
+  return Math.sqrt(dx * dx + dy * dy);
+};