@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/src/charts/maps/geo/routes.ts

@@ -0,0 +1,95 @@
+import type { Position } from "./types.js";
+
+const RAD = Math.PI / 180;
+
+type Vector = [number, number, number];
+
+function toVector([lon, lat]: Position): Vector {
+  const phi = lat * RAD;
+  const lambda = lon * RAD;
+  return [Math.cos(phi) * Math.cos(lambda), Math.cos(phi) * Math.sin(lambda), Math.sin(phi)];
+}
+
+function fromVector([x, y, z]: Vector): Position {
+  return [Math.atan2(y, x) / RAD, Math.asin(Math.max(-1, Math.min(1, z))) / RAD];
+}
+
+function angle(a: Vector, b: Vector): number {
+  return Math.acos(Math.max(-1, Math.min(1, a[0] * b[0] + a[1] * b[1] + a[2] * b[2])));
+}
+
+/**
+ * Points of the great circle (the shortest path on the globe) from `a` to `b`, `steps + 1` of
+ * them, as `[lon, lat]`. The path is cut into pieces where it crosses the antimeridian, so a
+ * projected line never streaks across the whole map.
+ */
+export function greatCircle(a: Position, b: Position, steps = 48): Position[][] {
+  const va = toVector(a);
+  const vb = toVector(b);
+  const omega = angle(va, vb);
+  const count = Math.max(1, Math.round(steps));
+  const points: Position[] = [];
+  for (let i = 0; i <= count; i += 1) {
+    if (omega < 1e-9) {
+      points.push(a);
+      continue;
+    }
+    const t = i / count;
+    const wa = Math.sin((1 - t) * omega) / Math.sin(omega);
+    const wb = Math.sin(t * omega) / Math.sin(omega);
+    points.push(
+      fromVector([wa * va[0] + wb * vb[0], wa * va[1] + wb * vb[1], wa * va[2] + wb * vb[2]]),
+    );
+  }
+  // Keep the exact ends the caller gave: the trigonometric round trip drifts in the last digits.
+  points[0] = a;
+  points[points.length - 1] = b;
+  const pieces: Position[][] = [[points[0] as Position]];
+  for (let i = 1; i < points.length; i += 1) {
+    const previous = points[i - 1] as Position;
+    const point = points[i] as Position;
+    if (Math.abs(point[0] - previous[0]) > 180) pieces.push([]);
+    (pieces[pieces.length - 1] as Position[]).push(point);
+  }
+  return pieces;
+}
+
+/** Angular length of the great circle between two positions, in degrees. */
+export function greatCircleDistance(a: Position, b: Position): number {
+  return angle(toVector(a), toVector(b)) / RAD;
+}
+
+/**
+ * Control point of a quadratic curve from `a` to `b`: the midpoint pushed sideways by `bend`
+ * times the distance (0 is a straight line, 0.25 a soft arch). With y pointing down a positive
+ * `bend` bulges to the left of the travel direction.
+ */
+export function routeControl(
+  a: readonly [number, number],
+  b: readonly [number, number],
+  bend = 0.25,
+): [number, number] {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  return [(a[0] + b[0]) / 2 + dy * bend, (a[1] + b[1]) / 2 - dx * bend];
+}
+
+/** SVG path of a quadratic arc. */
+export function routeArcPath(
+  a: readonly [number, number],
+  b: readonly [number, number],
+  bend = 0.25,
+): string {
+  const [cx, cy] = routeControl(a, b, bend);
+  return `M${a[0].toFixed(1)},${a[1].toFixed(1)}Q${cx.toFixed(1)},${cy.toFixed(1)} ${b[0].toFixed(1)},${b[1].toFixed(1)}`;
+}
+
+/** SVG path of a polyline given as separate pieces (`greatCircle` output once projected). */
+export function routePolylinePath(
+  pieces: ReadonlyArray<ReadonlyArray<readonly [number, number]>>,
+): string {
+  return pieces
+    .filter((piece) => piece.length > 1)
+    .map((piece) => `M${piece.map(([x, y]) => `${x.toFixed(1)},${y.toFixed(1)}`).join("L")}`)
+    .join("");
+}

package/src/charts/maps/geo/simplify.ts

@@ -0,0 +1,57 @@
+export type PlanePoint = readonly [number, number];
+
+function distanceToSegmentSquared(p: PlanePoint, a: PlanePoint, b: PlanePoint): number {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const lengthSquared = dx * dx + dy * dy;
+  let t = lengthSquared === 0 ? 0 : ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / lengthSquared;
+  t = Math.max(0, Math.min(1, t));
+  const x = a[0] + t * dx - p[0];
+  const y = a[1] + t * dy - p[1];
+  return x * x + y * y;
+}
+
+/**
+ * Douglas-Peucker line simplification (iterative, so long coastlines cannot
+ * overflow the stack). The first and last points are always kept, which is
+ * what lets neighbouring regions keep sharing their borders: each shared arc
+ * is simplified once, with fixed ends. Points farther than `tolerance` from the
+ * simplified line are never dropped.
+ */
+export function simplifyLine<P extends PlanePoint>(points: readonly P[], tolerance: number): P[] {
+  const count = points.length;
+  if (count <= 2 || tolerance <= 0) return [...points];
+  const keep = new Uint8Array(count);
+  keep[0] = 1;
+  keep[count - 1] = 1;
+  const limit = tolerance * tolerance;
+  const stack: Array<[number, number]> = [[0, count - 1]];
+  while (stack.length > 0) {
+    const [from, to] = stack.pop() as [number, number];
+    let worst = -1;
+    let worstDistance = limit;
+    for (let i = from + 1; i < to; i++) {
+      const distance = distanceToSegmentSquared(points[i] as P, points[from] as P, points[to] as P);
+      if (distance > worstDistance) {
+        worst = i;
+        worstDistance = distance;
+      }
+    }
+    if (worst > 0) {
+      keep[worst] = 1;
+      stack.push([from, worst], [worst, to]);
+    }
+  }
+  return points.filter((_, index) => keep[index] === 1);
+}
+
+/** Signed area of a ring (shoelace); positive when counter-clockwise in a y-up plane. */
+export function ringArea(ring: readonly PlanePoint[]): number {
+  let sum = 0;
+  for (let i = 0, n = ring.length; i < n; i++) {
+    const [x0, y0] = ring[i] as PlanePoint;
+    const [x1, y1] = ring[(i + 1) % n] as PlanePoint;
+    sum += x0 * y1 - x1 * y0;
+  }
+  return sum / 2;
+}

package/src/charts/maps/geo/topojson.ts

@@ -0,0 +1,94 @@
+import type {
+  AreaGeometry,
+  GeoFeature,
+  GeoMap,
+  Position,
+  Topology,
+  TopologyGeometry,
+} from "./types.js";
+
+/**
+ * Minimal TopoJSON decoder for area objects. Arcs are stored quantized and
+ * delta-encoded; `decodeArcs` expands them once to absolute [lon, lat].
+ */
+export function decodeArcs(topology: Topology): Position[][] {
+  const transform = topology.transform;
+  return topology.arcs.map((arc) => {
+    let x = 0;
+    let y = 0;
+    return arc.map(([dx, dy]) => {
+      if (!transform) return [dx as number, dy as number] as const;
+      x += dx as number;
+      y += dy as number;
+      return [
+        x * transform.scale[0] + transform.translate[0],
+        y * transform.scale[1] + transform.translate[1],
+      ] as const;
+    });
+  });
+}
+
+/** Walks the arc list of one ring; `~i` is arc `i` backwards. Shared end points are not repeated. */
+export function stitchRing(arcs: readonly Position[][], indices: readonly number[]): Position[] {
+  const ring: Position[] = [];
+  for (const index of indices) {
+    const arc =
+      index < 0 ? [...(arcs[~index] as Position[])].reverse() : (arcs[index] as Position[]);
+    for (let i = ring.length > 0 ? 1 : 0; i < arc.length; i++) ring.push(arc[i] as Position);
+  }
+  return ring;
+}
+
+function geometryOf(arcs: readonly Position[][], geometry: TopologyGeometry): AreaGeometry {
+  if (geometry.type === "Polygon") {
+    return {
+      type: "Polygon",
+      coordinates: (geometry.arcs as number[][]).map((ring) => stitchRing(arcs, ring)),
+    };
+  }
+  return {
+    type: "MultiPolygon",
+    coordinates: (geometry.arcs as number[][][]).map((polygon) =>
+      polygon.map((ring) => stitchRing(arcs, ring)),
+    ),
+  };
+}
+
+/** Regions of a topology object as lon/lat features. Returns `[]` for an unknown object. */
+export function topologyFeatures(topology: Topology, object: string): GeoFeature[] {
+  const collection = topology.objects[object];
+  if (!collection) return [];
+  const arcs = decodeArcs(topology);
+  return collection.geometries.map((geometry, index) => ({
+    id: geometry.id ?? `${object}-${index}`,
+    name: geometry.properties?.name ?? geometry.id ?? `${index + 1}`,
+    geometry: geometryOf(arcs, geometry),
+  }));
+}
+
+/** All rings of a geometry, flattened (outer rings and holes). */
+export function geometryRings(geometry: AreaGeometry): Position[][] {
+  return geometry.type === "Polygon" ? geometry.coordinates : geometry.coordinates.flat();
+}
+
+/**
+ * A map restricted to some regions (by id), e.g. only Lima and Callao out of
+ * Peru. The projection is fitted to what is left, so the view zooms into it.
+ * Arcs are shared, not copied.
+ */
+export function selectRegions(map: GeoMap, ids: readonly string[]): GeoMap {
+  const object = map.topology.objects[map.object];
+  return {
+    ...map,
+    id: `${map.id}:${ids.join(",")}`,
+    topology: {
+      ...map.topology,
+      objects: {
+        [map.object]: {
+          type: "GeometryCollection",
+          geometries: (object?.geometries ?? []).filter((g) => g.id && ids.includes(g.id)),
+        },
+      },
+    },
+  };
+}

package/src/charts/maps/geo/types.ts

@@ -0,0 +1,59 @@
+/** `[lon, lat]` in degrees. */
+export type Position = readonly [number, number];
+
+export interface PolygonGeometry {
+  type: "Polygon";
+  /** Outer ring first, then holes. Rings are closed (first point equals the last). */
+  coordinates: Position[][];
+}
+
+export interface MultiPolygonGeometry {
+  type: "MultiPolygon";
+  coordinates: Position[][][];
+}
+
+export type AreaGeometry = PolygonGeometry | MultiPolygonGeometry;
+
+/** A region of a map: stable `id` (ISO code), display `name` and its geometry. */
+export interface GeoFeature {
+  id: string;
+  name: string;
+  geometry: AreaGeometry;
+}
+
+/** The subset of TopoJSON this library reads (quantized, delta-encoded arcs; areas only). */
+export interface TopologyGeometry {
+  type: "Polygon" | "MultiPolygon";
+  /** Polygon: rings of arc indices. MultiPolygon: polygons of rings. A negative index `~i` walks arc `i` backwards. */
+  arcs: number[][] | number[][][];
+  id?: string;
+  properties?: { name?: string };
+}
+
+export interface TopologyObject {
+  type: "GeometryCollection";
+  geometries: TopologyGeometry[];
+}
+
+export interface Topology {
+  type: "Topology";
+  /** Present when `arcs` hold quantized integers, delta-encoded. */
+  transform?: { scale: readonly [number, number]; translate: readonly [number, number] };
+  arcs: number[][][];
+  objects: Record<string, TopologyObject>;
+}
+
+export type ProjectionKind = "equirectangular" | "mercator" | "equalEarth" | "fitted";
+
+/** A shippable map: its topology, the object to draw and the projection that suits it. */
+export interface GeoMap {
+  id: string;
+  /** Accessible name of the area, e.g. "Perú". */
+  name: string;
+  topology: Topology;
+  /** Key in `topology.objects`. */
+  object: string;
+  projection: ProjectionKind;
+}
+
+export type Bounds = readonly [minX: number, minY: number, maxX: number, maxY: number];

package/src/charts/maps/geo/use-map-geometry.ts

@@ -0,0 +1,132 @@
+"use client";
+
+import { useMemo } from "react";
+import { featurePositions, geometryExtent, geometryPath, labelAnchor } from "./geo-path.js";
+import { fitProjection, type Projection } from "./projection.js";
+import { topologyFeatures } from "./topojson.js";
+import type { Bounds, GeoFeature, GeoMap, Position, ProjectionKind } from "./types.js";
+
+const featureCache = new WeakMap<GeoMap, GeoFeature[]>();
+const anchorCache = new WeakMap<GeoFeature[], Position[]>();
+
+/** Decoded features of a map (once per map object, not per render). */
+export function mapFeatures(map: GeoMap): GeoFeature[] {
+  let features = featureCache.get(map);
+  if (!features) {
+    features = topologyFeatures(map.topology, map.object);
+    featureCache.set(map, features);
+  }
+  return features;
+}
+
+function anchorsOf(features: GeoFeature[]): Position[] {
+  let anchors = anchorCache.get(features);
+  if (!anchors) {
+    anchors = features.map((feature) => labelAnchor(feature.geometry));
+    anchorCache.set(features, anchors);
+  }
+  return anchors;
+}
+
+const aspectCache = new WeakMap<GeoMap, Map<string, number>>();
+
+/**
+ * Height that suits `map` at `width`: its own projected height / width ratio, so a tall country gets a tall
+ * box and a world map a wide one (within 220 and 640 px).
+ */
+export function defaultMapHeight(map: GeoMap, width: number, projection?: ProjectionKind): number {
+  const kind = projection ?? map.projection;
+  let byKind = aspectCache.get(map);
+  if (!byKind) {
+    byKind = new Map();
+    aspectCache.set(map, byKind);
+  }
+  let aspect = byKind.get(kind);
+  if (aspect === undefined) {
+    const positions = featurePositions(mapFeatures(map));
+    const fitted = fitProjection(kind, positions, 1000, 1000, { padding: 0 });
+    const projected = positions.map(([lon, lat]) => fitted.project(lon, lat));
+    const [x0, y0, x1, y1] = [
+      Math.min(...projected.map((p) => p[0])),
+      Math.min(...projected.map((p) => p[1])),
+      Math.max(...projected.map((p) => p[0])),
+      Math.max(...projected.map((p) => p[1])),
+    ];
+    aspect = (y1 - y0) / Math.max(1, x1 - x0);
+    byKind.set(kind, aspect);
+  }
+  return Math.round(Math.min(640, Math.max(220, width * aspect)));
+}
+
+/** A map fitted to a box: everything the drawing layers need, in zoom 1 pixels. */
+export interface MapGeometry {
+  features: GeoFeature[];
+  projection: Projection;
+  /** SVG path of each region. */
+  paths: string[];
+  /** Label position of each region. */
+  anchors: Array<[number, number]>;
+  /** Pixel box of each region. */
+  boxes: Bounds[];
+  /** Pixel box of the whole map. */
+  bounds: Bounds;
+}
+
+/**
+ * Fits `map` into `width` x `height`. Recomputes paths only when the box, the
+ * map or the projection changes, never on hover, zoom or pan (those only move
+ * a transform).
+ */
+export function useMapGeometry(
+  map: GeoMap,
+  width: number,
+  height: number,
+  { projection, padding = 8 }: { projection?: ProjectionKind; padding?: number } = {},
+): MapGeometry {
+  return useMemo(() => {
+    const features = mapFeatures(map);
+    const projectionFit = fitProjection(
+      projection ?? map.projection,
+      featurePositions(features),
+      width,
+      height,
+      { padding },
+    );
+    const project = projectionFit.project;
+    const lonLatAnchors = anchorsOf(features);
+    const boxes = features.map((feature): Bounds => {
+      const [west, south, east, north] = geometryExtent(feature.geometry);
+      const corners = [
+        project(west, south),
+        project(east, south),
+        project(east, north),
+        project(west, north),
+      ];
+      const xs = corners.map((corner) => corner[0]);
+      const ys = corners.map((corner) => corner[1]);
+      return [Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys)];
+    });
+    const bounds: Bounds = boxes.reduce<Bounds>(
+      (all, box) => [
+        Math.min(all[0], box[0]),
+        Math.min(all[1], box[1]),
+        Math.max(all[2], box[2]),
+        Math.max(all[3], box[3]),
+      ],
+      [
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.NEGATIVE_INFINITY,
+        Number.NEGATIVE_INFINITY,
+      ],
+    );
+    return {
+      features,
+      projection: projectionFit,
+      paths: features.map((feature) => geometryPath(feature.geometry, project, 1)),
+      anchors: lonLatAnchors.map(([lon, lat]) => project(lon, lat)),
+      boxes,
+      bounds,
+    };
+  }, [map, width, height, projection, padding]);
+}

package/src/charts/maps/geo/use-map-view.ts

@@ -0,0 +1,253 @@
+"use client";
+
+import { type PointerEvent, type RefObject, useCallback, useEffect, useRef, useState } from "react";
+import { useReducedMotion } from "../../core/motion.js";
+import type { Bounds } from "./types.js";
+import {
+  clampView,
+  DEFAULT_LIMITS,
+  IDENTITY_VIEW,
+  type MapView,
+  viewFitting,
+  zoomAt,
+} from "./view.js";
+
+export interface UseMapViewOptions {
+  width: number;
+  height: number;
+  /** Pixel box of the map at zoom 1. */
+  content: Bounds;
+  /** Wheel, drag and pinch. Buttons and keyboard (`zoomBy`, `fit`) always work. */
+  gestures: boolean;
+  /** "always": the wheel zooms; "modifier" (default): only with Ctrl or Cmd held, so page scrolling is never trapped. */
+  wheelZoom?: "always" | "modifier";
+  minZoom?: number;
+  maxZoom?: number;
+  animate?: boolean;
+}
+
+const MOVE_THRESHOLD = 4;
+const DURATION = 220;
+
+function easeOut(t: number): number {
+  return 1 - (1 - t) ** 3;
+}
+
+/**
+ * Zoom and pan state of a map: wheel, drag, two-finger pinch, and imperative
+ * `zoomBy` / `fit` / `focusBox` for buttons, keyboard and cluster clicks. The
+ * view is always clamped so the map cannot be lost, and transitions are
+ * driven in JS (not CSS) so every layer, including the screen-space bubbles
+ * and labels, moves in step. Instant under `prefers-reduced-motion`.
+ */
+export function useMapView<E extends Element>({
+  width,
+  height,
+  content,
+  gestures,
+  wheelZoom = "modifier",
+  minZoom = DEFAULT_LIMITS.minZoom,
+  maxZoom = DEFAULT_LIMITS.maxZoom,
+  animate = true,
+}: UseMapViewOptions) {
+  const [view, setViewState] = useState<MapView>(IDENTITY_VIEW);
+  const [dragging, setDragging] = useState(false);
+  const reduced = useReducedMotion();
+  const ref = useRef<E | null>(null);
+  const viewRef = useRef(view);
+  const frame = useRef(0);
+  const contentRef = useRef({ width, height, content, minZoom, maxZoom });
+  contentRef.current = { width, height, content, minZoom, maxZoom };
+  const wasDragged = useRef(false);
+
+  const clamp = useCallback((next: MapView): MapView => {
+    const c = contentRef.current;
+    return clampView(next, c.width, c.height, c.content, {
+      minZoom: c.minZoom,
+      maxZoom: c.maxZoom,
+    });
+  }, []);
+
+  const apply = useCallback(
+    (next: MapView) => {
+      const clamped = clamp(next);
+      viewRef.current = clamped;
+      setViewState(clamped);
+    },
+    [clamp],
+  );
+
+  const cancelAnimation = useCallback(() => cancelAnimationFrame(frame.current), []);
+
+  const animateTo = useCallback(
+    (target: MapView) => {
+      cancelAnimationFrame(frame.current);
+      const goal = clamp(target);
+      if (!animate || reduced || typeof requestAnimationFrame === "undefined") {
+        apply(goal);
+        return;
+      }
+      const from = viewRef.current;
+      const start = performance.now();
+      const step = (now: number) => {
+        const t = Math.min(1, (now - start) / DURATION);
+        const e = easeOut(t);
+        // Interpolate zoom geometrically so the speed feels constant.
+        const k = from.k * (goal.k / from.k) ** e;
+        apply({ k, x: from.x + (goal.x - from.x) * e, y: from.y + (goal.y - from.y) * e });
+        if (t < 1) frame.current = requestAnimationFrame(step);
+      };
+      frame.current = requestAnimationFrame(step);
+    },
+    [animate, reduced, apply, clamp],
+  );
+
+  useEffect(() => () => cancelAnimationFrame(frame.current), []);
+
+  // A new box (resize, other data) re-fits: the old pixel offsets mean nothing now.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: only the box size resets the view.
+  useEffect(() => {
+    apply(IDENTITY_VIEW);
+  }, [width, height, apply]);
+
+  const zoomBy = useCallback(
+    (factor: number, cx = width / 2, cy = height / 2) =>
+      animateTo(zoomAt(viewRef.current, factor, cx, cy, contentRef.current)),
+    [animateTo, width, height],
+  );
+  const fit = useCallback(() => animateTo(IDENTITY_VIEW), [animateTo]);
+  const panBy = useCallback(
+    (dx: number, dy: number) => {
+      const current = viewRef.current;
+      animateTo({ ...current, x: current.x + dx, y: current.y + dy });
+    },
+    [animateTo],
+  );
+  /** Frames a pixel box (zoom 1 coordinates). */
+  const focusBox = useCallback(
+    (box: Bounds) => animateTo(viewFitting(box, width, height, { maxZoom })),
+    [animateTo, width, height, maxZoom],
+  );
+
+  const pointers = useRef(new Map<number, { x: number; y: number }>());
+  const gesture = useRef<{
+    view: MapView;
+    x: number;
+    y: number;
+    distance: number;
+    moved: boolean;
+  } | null>(null);
+
+  const local = (event: { clientX: number; clientY: number }) => {
+    const box = (ref.current as Element | null)?.getBoundingClientRect();
+    return { x: event.clientX - (box?.left ?? 0), y: event.clientY - (box?.top ?? 0) };
+  };
+  const center = () => {
+    const points = [...pointers.current.values()];
+    const x = points.reduce((sum, p) => sum + p.x, 0) / points.length;
+    const y = points.reduce((sum, p) => sum + p.y, 0) / points.length;
+    const [a, b] = points;
+    const distance = a && b ? Math.hypot(a.x - b.x, a.y - b.y) : 0;
+    return { x, y, distance };
+  };
+
+  const onPointerDown = (event: PointerEvent<E>) => {
+    if (!gestures || (event.pointerType === "mouse" && event.button !== 0)) return;
+    cancelAnimation();
+    wasDragged.current = false;
+    pointers.current.set(event.pointerId, local(event));
+    const c = center();
+    gesture.current = { view: viewRef.current, x: c.x, y: c.y, distance: c.distance, moved: false };
+  };
+
+  const onPointerMove = (event: PointerEvent<E>) => {
+    if (!gestures || !pointers.current.has(event.pointerId) || !gesture.current) return;
+    pointers.current.set(event.pointerId, local(event));
+    const g = gesture.current;
+    const c = center();
+    if (!g.moved && Math.hypot(c.x - g.x, c.y - g.y) < MOVE_THRESHOLD && pointers.current.size < 2)
+      return;
+    if (!g.moved) {
+      g.moved = true;
+      wasDragged.current = true;
+      setDragging(true);
+      try {
+        (event.currentTarget as Element).setPointerCapture(event.pointerId);
+      } catch {
+        // Pointer already released.
+      }
+    }
+    let next = { ...g.view, x: g.view.x + (c.x - g.x), y: g.view.y + (c.y - g.y) };
+    if (pointers.current.size >= 2 && g.distance > 0) {
+      next = zoomAt(g.view, c.distance / g.distance, g.x, g.y, contentRef.current);
+      next = { ...next, x: next.x + (c.x - g.x), y: next.y + (c.y - g.y) };
+    }
+    apply(next);
+  };
+
+  const release = (event: PointerEvent<E>) => {
+    pointers.current.delete(event.pointerId);
+    if (pointers.current.size === 0) {
+      gesture.current = null;
+      setDragging(false);
+    } else {
+      const c = center();
+      gesture.current = {
+        view: viewRef.current,
+        x: c.x,
+        y: c.y,
+        distance: c.distance,
+        moved: true,
+      };
+    }
+  };
+
+  // The wheel listener must be non-passive to cancel page scrolling while zooming.
+  useEffect(() => {
+    const element = ref.current;
+    if (!gestures || !element) return;
+    const onWheel = (event: Event) => {
+      const wheel = event as WheelEvent;
+      if (wheelZoom === "modifier" && !(wheel.ctrlKey || wheel.metaKey)) return;
+      const current = viewRef.current;
+      const out = wheel.deltaY > 0;
+      const limitsNow = contentRef.current;
+      // At the zoom floor, scrolling "out" belongs to the page.
+      if (out && current.k <= limitsNow.minZoom + 1e-6) return;
+      event.preventDefault();
+      cancelAnimationFrame(frame.current);
+      const unit = wheel.deltaMode === 1 ? 16 : wheel.deltaMode === 2 ? 400 : 1;
+      const speed = wheel.ctrlKey ? 0.01 : 0.0018;
+      const box = element.getBoundingClientRect();
+      apply(
+        zoomAt(
+          current,
+          Math.exp(-wheel.deltaY * unit * speed),
+          wheel.clientX - box.left,
+          wheel.clientY - box.top,
+          limitsNow,
+        ),
+      );
+    };
+    element.addEventListener("wheel", onWheel, { passive: false });
+    return () => element.removeEventListener("wheel", onWheel);
+  }, [gestures, wheelZoom, apply]);
+
+  return {
+    ref: ref as RefObject<E | null>,
+    view,
+    dragging,
+    /** True right after a drag ended: the click that follows must be ignored. */
+    wasDragged: () => wasDragged.current,
+    zoomBy,
+    fit,
+    panBy,
+    focusBox,
+    animateTo,
+    canZoomIn: view.k < maxZoom - 1e-6,
+    canZoomOut: view.k > minZoom + 1e-6,
+    pointerProps: { onPointerDown, onPointerMove, onPointerUp: release, onPointerCancel: release },
+  };
+}
+
+export type MapViewController = ReturnType<typeof useMapView<SVGSVGElement>>;