@dxos/solid-ui-geo 0.0.0

package/src/hooks/useTour.ts

@@ -0,0 +1,124 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { selection as d3Selection, geoDistance, geoInterpolate, geoPath } from 'd3';
+import { type Accessor, type Setter, createEffect, createSignal, onCleanup } from 'solid-js';
+import versor from 'versor';
+
+import type { GlobeController } from '../components';
+import { type LatLngLiteral } from '../types';
+import { type StyleSet, geoToPosition, positionToRotation } from '../util';
+
+const TRANSITION_NAME = 'globe-tour';
+
+const defaultDuration = 1_500;
+
+export type TourOptions = {
+  running?: boolean;
+  disabled?: boolean;
+  duration?: number;
+  loop?: boolean;
+  tilt?: number;
+  autoRotate?: boolean;
+  styles?: StyleSet;
+};
+
+/**
+ * Iterates between points.
+ * Inspired by: https://observablehq.com/@mbostock/top-100-cities
+ */
+export const useTour = (
+  controller?: GlobeController | null,
+  points?: LatLngLiteral[],
+  options: TourOptions = {},
+): { running: Accessor<boolean>; setRunning: Setter<boolean> } => {
+  const selection = d3Selection();
+  const [running, setRunning] = createSignal(options.running ?? false);
+
+  createEffect(() => {
+    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 = geoPath(projection, context).pointRadius(2);
+
+        const tilt = options.tilt ?? 0;
+        let last: LatLngLiteral;
+        try {
+          const p = [...(points ?? [])];
+          if (options.loop) {
+            p.push(p[0]);
+          }
+
+          for (const next of p) {
+            if (!running()) {
+              break;
+            }
+
+            // 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 {
+          setRunning(false);
+        }
+      });
+
+      onCleanup(() => {
+        clearTimeout(t);
+        selection.interrupt(TRANSITION_NAME);
+      });
+    }
+  });
+
+  return { running, setRunning };
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './components';
+export * from './data';
+export * from './hooks';
+export * from './translations';
+export type * from './types';
+export * from './util';

package/src/translations.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const translationKey = '@dxos/react-ui-geo';
+
+export const translations = [
+  {
+    'en-US': {
+      [translationKey]: {
+        'zoom in icon button': 'Zoom in',
+        'zoom out icon button': 'Zoom out',
+        'start icon button': 'Start',
+        'toggle icon button': 'Toggle',
+      },
+    },
+  },
+] as const;

package/src/types.ts

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

package/src/util/debug.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 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 2025 DXOS.org
+//
+
+export * from './debug';
+export * from './inertia';
+export * from './path';
+export * from './render';

package/src/util/inertia.ts

@@ -0,0 +1,196 @@
+//
+// Copyright 2017 Philippe Rivière
+// Copyright 2025 DXOS.org
+// https://github.com/Fil/d3-inertia
+//
+
+import { drag, select, timer } 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 = 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(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: 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,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type GeoGeometryObjects, geoCircle as d3GeoCircle } from 'd3';
+import { type Point, type Polygon, type Position } from 'geojson';
+import { type LatLngLiteral } from 'leaflet';
+
+import type { Vector } from '../hooks';
+
+export const positionToRotation = ([lng, lat]: [number, number], tilt = 0): Vector => [-lng, tilt - lat, 0];
+
+export const geoToPosition = ({ lat, lng }: LatLngLiteral): [number, number] => [lng, lat];
+
+export const geoPoint = (point: LatLngLiteral): Point => ({ type: 'Point', coordinates: geoToPosition(point) });
+
+// https://github.com/d3/d3-geo#geoCircle
+export const geoCircle = ({ lat, lng }: LatLngLiteral, radius: number): Polygon =>
+  d3GeoCircle().radius(radius).center([lng, lat])();
+
+export const geoLine = (p1: LatLngLiteral, p2: LatLngLiteral): 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);
+};

package/src/util/render.ts

@@ -0,0 +1,164 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type GeoPath, type GeoPermissibleObjects, geoGraticule } from 'd3';
+import { feature, mesh } from 'topojson-client';
+import { type Topology } from 'topojson-specification';
+
+import { type LatLngLiteral } from '../types';
+
+import { geoLine, geoPoint } from './path';
+
+export type Styles = Record<string, any>;
+
+export type Style =
+  | 'background'
+  | 'water'
+  | 'graticule'
+  | 'land'
+  | 'border'
+  | 'dots'
+  | 'point'
+  | 'line'
+  | 'cursor'
+  | 'arc';
+
+export type StyleSet = Partial<Record<Style, Styles>>;
+
+export type Features = {
+  points?: LatLngLiteral[];
+  lines?: { source: LatLngLiteral; target: LatLngLiteral }[];
+};
+
+export type Layer = {
+  styles: Styles;
+  path: GeoPermissibleObjects;
+};
+
+/**
+ * Create rendering layers.
+ */
+export const createLayers = (topology: Topology, features: Features, styles: StyleSet): Layer[] => {
+  const layers: Layer[] = [];
+
+  if (styles.water) {
+    layers.push({
+      styles: styles.water,
+      path: {
+        type: 'Sphere',
+      },
+    });
+  }
+
+  if (styles.graticule) {
+    layers.push({
+      styles: styles.graticule,
+      path: geoGraticule().step([6, 6])(),
+    });
+  }
+
+  //
+  // Topology.
+  //
+
+  if (topology) {
+    if (topology.objects.land && styles.land) {
+      layers.push({
+        styles: styles.land,
+        path: feature(topology, topology.objects.land),
+      });
+    }
+
+    if (topology.objects.countries && styles.border) {
+      layers.push({
+        styles: styles.border,
+        path: mesh(topology, topology.objects.countries, (a: any, b: any) => a !== b),
+      });
+    }
+
+    if (topology.objects.dots && styles.dots) {
+      layers.push({
+        styles: styles.dots,
+        path: topology.objects.dots as any, // TODO(burdon): Type.
+      });
+    }
+  }
+
+  //
+  // Features.
+  //
+
+  if (features) {
+    const { points, lines } = features;
+
+    if (points && styles.point) {
+      layers.push({
+        styles: styles.point,
+        path: {
+          type: 'GeometryCollection',
+          geometries: points.map((point) => geoPoint(point)),
+        },
+      });
+    }
+
+    if (lines && styles.line) {
+      layers.push({
+        styles: styles.line,
+        path: {
+          type: 'GeometryCollection',
+          geometries: lines.map(({ source, target }) => geoLine(source, target)),
+        },
+      });
+    }
+  }
+
+  return layers;
+};
+
+/**
+ * Render layers created above.
+ */
+export const renderLayers = (generator: GeoPath, layers: Layer[] = [], scale: number, styles: StyleSet) => {
+  const context: CanvasRenderingContext2D = generator.context();
+  const {
+    canvas: { width, height },
+  } = context;
+  context.reset();
+
+  // Clear background.
+  if (styles.background) {
+    context.fillStyle = styles.background.fillStyle;
+    context.fillRect(0, 0, width, height);
+  } else {
+    context.clearRect(0, 0, width, height);
+  }
+
+  // Render features.
+  // https://github.com/d3/d3-geo#_path
+  layers.forEach(({ path, styles }) => {
+    context.save();
+    let fill = false;
+    let stroke = false;
+    if (styles) {
+      Object.entries(styles).forEach(([key, value]) => {
+        if (key === 'pointRadius') {
+          generator.pointRadius(value * scale);
+        } else {
+          context[key] = value;
+          fill ||= key === 'fillStyle';
+          stroke ||= key === 'strokeStyle';
+        }
+      });
+    }
+
+    context.beginPath();
+
+    generator(path);
+    fill && context.fill();
+    stroke && context.stroke();
+    context.restore();
+  });
+
+  return context;
+};