@mui/x-charts-premium 9.8.0 → 9.10.0

package/internals/plugins/useGeoProjectionZoom/mapZoom.utils.js

@@ -0,0 +1,187 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WHEEL_ZOOM_STEP = exports.BUTTON_ZOOM_STEP = void 0;
+exports.clampTranslationAxis = clampTranslationAxis;
+exports.getDefaultMapInteraction = getDefaultMapInteraction;
+exports.getProjectionFamily = getProjectionFamily;
+exports.getRotation = getRotation;
+exports.getTranslation = getTranslation;
+var _d3Geo = require("@mui/x-charts-vendor/d3-geo");
+var _internals = require("@mui/x-charts/internals");
+var _useGeoProjection = require("../useGeoProjection/useGeoProjection.selectors");
+var _createGetVisibleCoordinate = require("../../createGetVisibleCoordinate");
+var _rotationMath = require("./rotationMath");
+/** Multiplicative zoom step applied per wheel tick. */
+const WHEEL_ZOOM_STEP = exports.WHEEL_ZOOM_STEP = 1.1;
+/** Multiplicative zoom step applied per `zoomIn`/`zoomOut` call. */
+const BUTTON_ZOOM_STEP = exports.BUTTON_ZOOM_STEP = 1.3;
+const PROJECTION_FAMILY = {
+  azimuthalEqualArea: 'azimuthal',
+  azimuthalEquidistant: 'azimuthal',
+  gnomonic: 'azimuthal',
+  orthographic: 'azimuthal',
+  stereographic: 'azimuthal',
+  conicConformal: 'conic',
+  conicEqualArea: 'conic',
+  conicEquidistant: 'conic',
+  albers: 'conic',
+  albersUsa: 'albersUsa',
+  equirectangular: 'cylindrical',
+  mercator: 'cylindrical',
+  transverseMercator: 'cylindrical',
+  equalEarth: 'cylindrical',
+  naturalEarth1: 'cylindrical'
+};
+
+/**
+ * The interaction that feels natural for each projection family, used as the default for
+ * `rotationAllowed`/`translationAllowed` when the consumer does not set them explicitly.
+ */
+const FAMILY_INTERACTION = {
+  azimuthal: {
+    rotationAllowed: 'both',
+    translationAllowed: 'none'
+  },
+  cylindrical: {
+    rotationAllowed: 'longitude',
+    translationAllowed: 'y'
+  },
+  conic: {
+    rotationAllowed: 'none',
+    translationAllowed: 'both'
+  },
+  albersUsa: {
+    rotationAllowed: 'none',
+    translationAllowed: 'both'
+  }
+};
+function getProjectionFamily(projection) {
+  if (projection == null) {
+    return 'cylindrical'; // fallback to avoid useless edge cases
+  }
+  if (typeof projection === 'string') {
+    return PROJECTION_FAMILY[projection] ?? 'cylindrical';
+  }
+
+  // Try to guess if users provided custom projection
+
+  // Conic projections expose the `parallels` accessor (e.g. conicConformal, albers).
+  if ('parallels' in projection) {
+    return 'conic';
+  }
+  // Composite projections such as `albersUsa` stitch several conics together and so drop `rotate`
+  // (there is no single sphere to spin). Treat them like the conic family they are built from.
+  if (typeof projection.rotate !== 'function') {
+    return 'conic';
+  }
+  // Azimuthal projections clip the sphere to a disc, so their clip angle sits strictly between 0 and
+  // 180° (e.g. 90° for orthographic). Flat projections leave it at 0° (no clipping).
+  const clipAngle = projection.clipAngle?.();
+  if (typeof clipAngle === 'number' && clipAngle > 0 && clipAngle < 180) {
+    return 'azimuthal';
+  }
+  return 'cylindrical';
+}
+function getDefaultMapInteraction(projection) {
+  return FAMILY_INTERACTION[getProjectionFamily(projection)];
+}
+
+/**
+ * For a given projection, apply a zoom factor to the scale and return the rotation that renders
+ * `geoPoint` at the `to` pixel coordinates, as `[longitude, latitude, roll]` (the view `center` plus
+ * the third d3 rotation angle).
+ *
+ * - With `rotationAllowed: 'both+roll'`, the roll is free to move but kept as stable as possible: the
+ *   shortest-arc rotation dragging `geoPoint` onto `to` is composed with the current orientation, so
+ *   the roll only drifts as much as strictly required.
+ * - With `rotationAllowed: 'both'`, both longitude and latitude are free but the roll is kept fixed at
+ *   the current value.
+ * - With `rotationAllowed: 'longitude'`, only the longitude is solved; the latitude and roll are kept fixed.
+ * - With `rotationAllowed: 'none'`, `null` is returned so the caller keeps the current rotation.
+ */
+function getRotation(projection, geoPoint, to, zoomFactor = 1, rotationAllowed = 'both') {
+  if (!projection.invert || !projection.rotate) {
+    return null;
+  }
+  const rotate = projection.rotate?.();
+  const scale = projection.scale();
+  projection.scale(scale * zoomFactor);
+  projection.rotate?.([0, 0]);
+  const q = (0, _createGetVisibleCoordinate.createGetVisibleCoordinate)(projection)(to);
+
+  // Reset projection modifications to avoid side effects.
+  projection.rotate?.(rotate);
+  projection.scale(scale);
+  if (!geoPoint || !q) {
+    return null;
+  }
+  switch (rotationAllowed) {
+    case 'both+roll':
+      return (0, _rotationMath.getMinimalRollRotation)(rotate, geoPoint, q);
+    case 'both':
+      return (0, _rotationMath.getNoRollRotation)(rotate, geoPoint, q);
+    case 'longitude':
+      return (0, _rotationMath.getLongitudeRotation)(rotate, geoPoint, q);
+    case 'none':
+    default:
+      return null;
+  }
+}
+function clampTranslationAxis(value, init, boundingBox0, boundingBox1, areaStart, areaEnd, gap) {
+  // Get min/mas translation allowed
+  const max = areaStart - boundingBox0 + init + gap;
+  const min = areaEnd - boundingBox1 + init - gap;
+  if (min > max) {
+    // If not translation accept the movement only if it reduces the gap
+    const prevGap0 = boundingBox0 - areaStart;
+    const prevGap1 = areaEnd - boundingBox1;
+    const gap = value - init;
+    const nextGap0 = boundingBox0 + gap - areaStart;
+    const nextGap1 = areaEnd - (boundingBox1 + gap);
+    if (Math.max(prevGap0, prevGap1) > Math.max(nextGap0, nextGap1)) {
+      return value;
+    }
+    return init;
+  }
+  return Math.min(max, Math.max(min, value));
+}
+function getTranslation(store, projection, geoPoint, to, translationAllowed = 'both', maxEmptySpace = 0, currentTranslation = [0, 0]) {
+  if (!projection.invert || translationAllowed === 'none') {
+    return null;
+  }
+  const q = (0, _createGetVisibleCoordinate.createGetVisibleCoordinate)(projection)(to);
+  if (!geoPoint || !q) {
+    return null;
+  }
+  const allowX = translationAllowed === 'both' || translationAllowed === 'x';
+  const allowY = translationAllowed === 'both' || translationAllowed === 'y';
+  const projectedGeoPoint = projection(geoPoint);
+  const projectedQ = projection(q);
+  if (!projectedGeoPoint || !projectedQ) {
+    return null;
+  }
+  const deltaX = projectedQ[0] - projectedGeoPoint[0];
+  const deltaY = projectedQ[1] - projectedGeoPoint[1];
+  const initTranslation = projection.translate();
+  const drawingArea = (0, _internals.selectorChartDrawingArea)(store.state);
+  let tx = currentTranslation[0];
+  let ty = currentTranslation[1];
+
+  // Clamp translation
+  const geoData = Number.isFinite(maxEmptySpace) ? (0, _useGeoProjection.selectorChartGeoData)(store.state) : null;
+  if (geoData) {
+    const [[bx0, by0], [bx1, by1]] = (0, _d3Geo.geoPath)(projection).bounds(geoData);
+    if (allowX) {
+      const translationX = clampTranslationAxis(initTranslation[0] + deltaX, initTranslation[0], bx0, bx1, drawingArea.left, drawingArea.left + drawingArea.width, maxEmptySpace * drawingArea.width);
+      tx = (translationX - drawingArea.left - drawingArea.width / 2) / drawingArea.width;
+    }
+    if (allowY) {
+      const translationY = clampTranslationAxis(initTranslation[1] + deltaY, initTranslation[1], by0, by1, drawingArea.top, drawingArea.top + drawingArea.height, maxEmptySpace * drawingArea.height);
+      ty = (translationY - drawingArea.top - drawingArea.height / 2) / drawingArea.height;
+    }
+  }
+  return [tx, ty];
+}

package/internals/plugins/useGeoProjectionZoom/mapZoom.utils.mjs

@@ -0,0 +1,177 @@
+import { geoPath } from '@mui/x-charts-vendor/d3-geo';
+import { selectorChartDrawingArea } from '@mui/x-charts/internals';
+import { selectorChartGeoData } from "../useGeoProjection/useGeoProjection.selectors.mjs";
+import { createGetVisibleCoordinate } from "../../createGetVisibleCoordinate.mjs";
+import { getLongitudeRotation, getMinimalRollRotation, getNoRollRotation } from "./rotationMath.mjs";
+
+/** Multiplicative zoom step applied per wheel tick. */
+export const WHEEL_ZOOM_STEP = 1.1;
+/** Multiplicative zoom step applied per `zoomIn`/`zoomOut` call. */
+export const BUTTON_ZOOM_STEP = 1.3;
+const PROJECTION_FAMILY = {
+  azimuthalEqualArea: 'azimuthal',
+  azimuthalEquidistant: 'azimuthal',
+  gnomonic: 'azimuthal',
+  orthographic: 'azimuthal',
+  stereographic: 'azimuthal',
+  conicConformal: 'conic',
+  conicEqualArea: 'conic',
+  conicEquidistant: 'conic',
+  albers: 'conic',
+  albersUsa: 'albersUsa',
+  equirectangular: 'cylindrical',
+  mercator: 'cylindrical',
+  transverseMercator: 'cylindrical',
+  equalEarth: 'cylindrical',
+  naturalEarth1: 'cylindrical'
+};
+
+/**
+ * The interaction that feels natural for each projection family, used as the default for
+ * `rotationAllowed`/`translationAllowed` when the consumer does not set them explicitly.
+ */
+const FAMILY_INTERACTION = {
+  azimuthal: {
+    rotationAllowed: 'both',
+    translationAllowed: 'none'
+  },
+  cylindrical: {
+    rotationAllowed: 'longitude',
+    translationAllowed: 'y'
+  },
+  conic: {
+    rotationAllowed: 'none',
+    translationAllowed: 'both'
+  },
+  albersUsa: {
+    rotationAllowed: 'none',
+    translationAllowed: 'both'
+  }
+};
+export function getProjectionFamily(projection) {
+  if (projection == null) {
+    return 'cylindrical'; // fallback to avoid useless edge cases
+  }
+  if (typeof projection === 'string') {
+    return PROJECTION_FAMILY[projection] ?? 'cylindrical';
+  }
+
+  // Try to guess if users provided custom projection
+
+  // Conic projections expose the `parallels` accessor (e.g. conicConformal, albers).
+  if ('parallels' in projection) {
+    return 'conic';
+  }
+  // Composite projections such as `albersUsa` stitch several conics together and so drop `rotate`
+  // (there is no single sphere to spin). Treat them like the conic family they are built from.
+  if (typeof projection.rotate !== 'function') {
+    return 'conic';
+  }
+  // Azimuthal projections clip the sphere to a disc, so their clip angle sits strictly between 0 and
+  // 180° (e.g. 90° for orthographic). Flat projections leave it at 0° (no clipping).
+  const clipAngle = projection.clipAngle?.();
+  if (typeof clipAngle === 'number' && clipAngle > 0 && clipAngle < 180) {
+    return 'azimuthal';
+  }
+  return 'cylindrical';
+}
+export function getDefaultMapInteraction(projection) {
+  return FAMILY_INTERACTION[getProjectionFamily(projection)];
+}
+
+/**
+ * For a given projection, apply a zoom factor to the scale and return the rotation that renders
+ * `geoPoint` at the `to` pixel coordinates, as `[longitude, latitude, roll]` (the view `center` plus
+ * the third d3 rotation angle).
+ *
+ * - With `rotationAllowed: 'both+roll'`, the roll is free to move but kept as stable as possible: the
+ *   shortest-arc rotation dragging `geoPoint` onto `to` is composed with the current orientation, so
+ *   the roll only drifts as much as strictly required.
+ * - With `rotationAllowed: 'both'`, both longitude and latitude are free but the roll is kept fixed at
+ *   the current value.
+ * - With `rotationAllowed: 'longitude'`, only the longitude is solved; the latitude and roll are kept fixed.
+ * - With `rotationAllowed: 'none'`, `null` is returned so the caller keeps the current rotation.
+ */
+export function getRotation(projection, geoPoint, to, zoomFactor = 1, rotationAllowed = 'both') {
+  if (!projection.invert || !projection.rotate) {
+    return null;
+  }
+  const rotate = projection.rotate?.();
+  const scale = projection.scale();
+  projection.scale(scale * zoomFactor);
+  projection.rotate?.([0, 0]);
+  const q = createGetVisibleCoordinate(projection)(to);
+
+  // Reset projection modifications to avoid side effects.
+  projection.rotate?.(rotate);
+  projection.scale(scale);
+  if (!geoPoint || !q) {
+    return null;
+  }
+  switch (rotationAllowed) {
+    case 'both+roll':
+      return getMinimalRollRotation(rotate, geoPoint, q);
+    case 'both':
+      return getNoRollRotation(rotate, geoPoint, q);
+    case 'longitude':
+      return getLongitudeRotation(rotate, geoPoint, q);
+    case 'none':
+    default:
+      return null;
+  }
+}
+export function clampTranslationAxis(value, init, boundingBox0, boundingBox1, areaStart, areaEnd, gap) {
+  // Get min/mas translation allowed
+  const max = areaStart - boundingBox0 + init + gap;
+  const min = areaEnd - boundingBox1 + init - gap;
+  if (min > max) {
+    // If not translation accept the movement only if it reduces the gap
+    const prevGap0 = boundingBox0 - areaStart;
+    const prevGap1 = areaEnd - boundingBox1;
+    const gap = value - init;
+    const nextGap0 = boundingBox0 + gap - areaStart;
+    const nextGap1 = areaEnd - (boundingBox1 + gap);
+    if (Math.max(prevGap0, prevGap1) > Math.max(nextGap0, nextGap1)) {
+      return value;
+    }
+    return init;
+  }
+  return Math.min(max, Math.max(min, value));
+}
+export function getTranslation(store, projection, geoPoint, to, translationAllowed = 'both', maxEmptySpace = 0, currentTranslation = [0, 0]) {
+  if (!projection.invert || translationAllowed === 'none') {
+    return null;
+  }
+  const q = createGetVisibleCoordinate(projection)(to);
+  if (!geoPoint || !q) {
+    return null;
+  }
+  const allowX = translationAllowed === 'both' || translationAllowed === 'x';
+  const allowY = translationAllowed === 'both' || translationAllowed === 'y';
+  const projectedGeoPoint = projection(geoPoint);
+  const projectedQ = projection(q);
+  if (!projectedGeoPoint || !projectedQ) {
+    return null;
+  }
+  const deltaX = projectedQ[0] - projectedGeoPoint[0];
+  const deltaY = projectedQ[1] - projectedGeoPoint[1];
+  const initTranslation = projection.translate();
+  const drawingArea = selectorChartDrawingArea(store.state);
+  let tx = currentTranslation[0];
+  let ty = currentTranslation[1];
+
+  // Clamp translation
+  const geoData = Number.isFinite(maxEmptySpace) ? selectorChartGeoData(store.state) : null;
+  if (geoData) {
+    const [[bx0, by0], [bx1, by1]] = geoPath(projection).bounds(geoData);
+    if (allowX) {
+      const translationX = clampTranslationAxis(initTranslation[0] + deltaX, initTranslation[0], bx0, bx1, drawingArea.left, drawingArea.left + drawingArea.width, maxEmptySpace * drawingArea.width);
+      tx = (translationX - drawingArea.left - drawingArea.width / 2) / drawingArea.width;
+    }
+    if (allowY) {
+      const translationY = clampTranslationAxis(initTranslation[1] + deltaY, initTranslation[1], by0, by1, drawingArea.top, drawingArea.top + drawingArea.height, maxEmptySpace * drawingArea.height);
+      ty = (translationY - drawingArea.top - drawingArea.height / 2) / drawingArea.height;
+    }
+  }
+  return [tx, ty];
+}

package/internals/plugins/useGeoProjectionZoom/rotationMath.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the new
+ * `[longitude, latitude, roll]` (the view `center` plus `roll`) that drags `geoPoint` onto the
+ * identity-frame screen coordinate `q` using the shortest-arc rotation composed with the current
+ * orientation. Because the delta is the minimal rotation moving the grabbed point to the target, the
+ * roll only changes as much as strictly required.
+ */
+export declare function getMinimalRollRotation(rotate: [number, number, number], geoPoint: [number, number], targetGeoPoint: [number, number]): [number, number, number];
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the
+ * `[longitude, latitude, roll]` that drags `geoPoint` onto the identity-frame screen coordinate
+ * `targetGeoPoint` while keeping the roll (`gamma`) unchanged: only the longitude and latitude move.
+ * When the target is out of reach for a roll-preserving rotation, the closest reachable orientation
+ * is returned.
+ */
+export declare function getNoRollRotation(rotate: [number, number, number], geoPoint: [number, number], targetGeoPoint: [number, number]): [number, number, number];
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the
+ * `[longitude, latitude, roll]` that pans `geoPoint` toward the identity-frame screen coordinate
+ * `targetGeoPoint` along the longitude axis only: the latitude and roll are left untouched and just
+ * the longitude is solved so `geoPoint` reaches the target's longitude.
+ */
+export declare function getLongitudeRotation(rotate: [number, number, number], geoPoint: [number, number], targetGeoPoint: [number, number]): [number, number, number];

package/internals/plugins/useGeoProjectionZoom/rotationMath.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the new
+ * `[longitude, latitude, roll]` (the view `center` plus `roll`) that drags `geoPoint` onto the
+ * identity-frame screen coordinate `q` using the shortest-arc rotation composed with the current
+ * orientation. Because the delta is the minimal rotation moving the grabbed point to the target, the
+ * roll only changes as much as strictly required.
+ */
+export declare function getMinimalRollRotation(rotate: [number, number, number], geoPoint: [number, number], targetGeoPoint: [number, number]): [number, number, number];
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the
+ * `[longitude, latitude, roll]` that drags `geoPoint` onto the identity-frame screen coordinate
+ * `targetGeoPoint` while keeping the roll (`gamma`) unchanged: only the longitude and latitude move.
+ * When the target is out of reach for a roll-preserving rotation, the closest reachable orientation
+ * is returned.
+ */
+export declare function getNoRollRotation(rotate: [number, number, number], geoPoint: [number, number], targetGeoPoint: [number, number]): [number, number, number];
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the
+ * `[longitude, latitude, roll]` that pans `geoPoint` toward the identity-frame screen coordinate
+ * `targetGeoPoint` along the longitude axis only: the latitude and roll are left untouched and just
+ * the longitude is solved so `geoPoint` reaches the target's longitude.
+ */
+export declare function getLongitudeRotation(rotate: [number, number, number], geoPoint: [number, number], targetGeoPoint: [number, number]): [number, number, number];

package/internals/plugins/useGeoProjectionZoom/rotationMath.js

@@ -0,0 +1,190 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getLongitudeRotation = getLongitudeRotation;
+exports.getMinimalRollRotation = getMinimalRollRotation;
+exports.getNoRollRotation = getNoRollRotation;
+const DEG = Math.PI / 180;
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+/**
+ * Rotate a `[longitude, latitude]` coordinate around the projection's center axis (the x-axis
+ * pointing to `[0, 0]`) by `gamma` degrees.
+ *
+ * This is the roll component of a d3 rotation `[lambda, phi, gamma]`, isolated so it can be undone
+ * on the target coordinate before solving the longitude/latitude rotation. A d3 rotation composes as
+ * `rollGamma ∘ geoRotation([lambda, phi])`, so pre-applying `rollGamma(-gamma)` to the target keeps
+ * the roll fixed while the yaw/pitch solver stays a two-angle problem.
+ */
+function rollCoordinate(coord, gamma) {
+  if (!gamma) {
+    return coord;
+  }
+  const g = gamma * DEG;
+  const cosG = Math.cos(g);
+  const sinG = Math.sin(g);
+  const lon = coord[0] * DEG;
+  const lat = coord[1] * DEG;
+  const x = Math.cos(lon) * Math.cos(lat);
+  const y = Math.sin(lon) * Math.cos(lat);
+  const z = Math.sin(lat);
+  // Rotation about the x-axis by `g`.
+  const yRolled = y * cosG - z * sinG;
+  const zRolled = y * sinG + z * cosG;
+  return [Math.atan2(yRolled, x) / DEG, Math.asin(clamp(zRolled, -1, 1)) / DEG];
+}
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+
+/**
+ * Unit vector on the sphere for a `[longitude, latitude]` coordinate (degrees).
+ */
+function unitVector([lonDeg, latDeg]) {
+  const lon = lonDeg * DEG;
+  const lat = latDeg * DEG;
+  const cosLat = Math.cos(lat);
+  return [Math.cos(lon) * cosLat, Math.sin(lon) * cosLat, Math.sin(lat)];
+}
+
+/**
+ * Rotate vector `v` around the unit axis `k` by `angle` radians (Rodrigues' rotation formula).
+ */
+function rotateAroundAxis(k, angle, v) {
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+  const dot = (k[0] * v[0] + k[1] * v[1] + k[2] * v[2]) * (1 - cos);
+  const kv = cross(k, v);
+  return [v[0] * cos + kv[0] * sin + k[0] * dot, v[1] * cos + kv[1] * sin + k[1] * dot, v[2] * cos + kv[2] * sin + k[2] * dot];
+}
+
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the new
+ * `[longitude, latitude, roll]` (the view `center` plus `roll`) that drags `geoPoint` onto the
+ * identity-frame screen coordinate `q` using the shortest-arc rotation composed with the current
+ * orientation. Because the delta is the minimal rotation moving the grabbed point to the target, the
+ * roll only changes as much as strictly required.
+ */
+function getMinimalRollRotation(rotate, geoPoint, targetGeoPoint) {
+  const l = rotate[0] * DEG;
+  const p = rotate[1] * DEG;
+  const g = (rotate[2] ?? 0) * DEG;
+  const cl = Math.cos(l);
+  const sl = Math.sin(l);
+  const cp = Math.cos(p);
+  const sp = Math.sin(p);
+  const cg = Math.cos(g);
+  const sg = Math.sin(g);
+
+  // Columns of the current rotation matrix `M = Rx(g)·Ry(-p)·Rz(l)`, which is exactly
+  // d3's `geoRotation([lambda, phi, gamma])` expressed on cartesian unit vectors.
+  const col0 = [cp * cl, cg * sl - sg * sp * cl, sg * sl + cg * sp * cl];
+  const col1 = [-cp * sl, cg * cl + sg * sp * sl, sg * cl - cg * sp * sl];
+  const col2 = [-sp, -sg * cp, cg * cp];
+  const point = unitVector(geoPoint);
+  // Where the grabbed point currently sits in the identity (screen) frame: `M · point`.
+  const current = [col0[0] * point[0] + col1[0] * point[1] + col2[0] * point[2], col0[1] * point[0] + col1[1] * point[1] + col2[1] * point[2], col0[2] * point[0] + col1[2] * point[1] + col2[2] * point[2]];
+  const target = unitVector(targetGeoPoint);
+
+  // Shortest-arc rotation taking `current` onto `target`, applied to `M` column by column
+  // (`M_new = delta · M`).
+  const axis = cross(current, target);
+  const s = Math.hypot(axis[0], axis[1], axis[2]);
+  let n0 = col0;
+  let n1 = col1;
+  let n2 = col2;
+  if (s > 1e-12) {
+    const dot = clamp(current[0] * target[0] + current[1] * target[1] + current[2] * target[2], -1, 1);
+    const angle = Math.atan2(s, dot);
+    const k = [axis[0] / s, axis[1] / s, axis[2] / s];
+    n0 = rotateAroundAxis(k, angle, col0);
+    n1 = rotateAroundAxis(k, angle, col1);
+    n2 = rotateAroundAxis(k, angle, col2);
+  }
+
+  // Decompose `M_new = Rx(g')·Ry(-p')·Rz(l')` back into d3 angles.
+  const phi = Math.asin(clamp(-n2[0], -1, 1));
+  const lambda = Math.atan2(-n1[0], n0[0]);
+  const gamma = Math.atan2(-n2[1], n2[2]);
+
+  // `rotate = [-center[0], -center[1], roll]`, so invert the sign for the view center.
+  return [-lambda / DEG, -phi / DEG, gamma / DEG];
+}
+
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the
+ * `[longitude, latitude, roll]` that drags `geoPoint` onto the identity-frame screen coordinate
+ * `targetGeoPoint` while keeping the roll (`gamma`) unchanged: only the longitude and latitude move.
+ * When the target is out of reach for a roll-preserving rotation, the closest reachable orientation
+ * is returned.
+ */
+function getNoRollRotation(rotate, geoPoint, targetGeoPoint) {
+  const roll = rotate[2] ?? 0;
+
+  // A d3 rotation composes as `rollGamma ∘ geoRotation([lambda, phi])`, so undo the roll on the
+  // target: what remains is a plain (roll-free) `Ry(-phi)·Rz(lambda)` mapping `geoPoint` onto it.
+  const [px, py, pz] = unitVector(geoPoint);
+  const [tx, ty, tz] = unitVector(rollCoordinate(targetGeoPoint, -roll));
+  const lambdaOld = rotate[0] * DEG;
+  const phiOld = rotate[1] * DEG;
+
+  // `Rz(lambda)` spins `geoPoint` on the circle of radius `r` in the xy-plane, keeping its
+  // z-component; `Ry(-phi)` then tilts it. So after `Rz` the y-component (`uy`) must already equal
+  // the target's, and the xy-radius bounds how far the latitude can reach.
+  const r = Math.hypot(px, py);
+  if (r < 1e-12) {
+    // `geoPoint` sits on a pole where `Rz(lambda)` is a no-op: keep the current longitude and only
+    // solve the tilt.
+    const phi = Math.atan2(tz, tx) - Math.atan2(pz, 0);
+    return [-lambdaOld / DEG, -phi / DEG, roll];
+  }
+
+  // `clamp` keeps the nearest reachable point when the target latitude is out of range (`|ty| > r`).
+  const uy = clamp(ty, -r, r);
+  const uxMagnitude = Math.sqrt(Math.max(0, r * r - uy * uy));
+  const solveFor = ux => ({
+    // `Rz(lambda)` rotates `(px, py)` onto `(ux, uy)`.
+    lambda: Math.atan2(uy, ux) - Math.atan2(py, px),
+    // `Ry(-phi)` rotates `(ux, pz)` onto `(tx, tz)`.
+    phi: Math.atan2(tz, tx) - Math.atan2(pz, ux)
+  });
+
+  // Two branches (`±ux`) solve the equation; pick the one closest to the current orientation so the
+  // rotation stays continuous while dragging.
+  const wrap = angle => Math.atan2(Math.sin(angle), Math.cos(angle));
+  const distanceToCurrent = ({
+    lambda,
+    phi
+  }) => Math.abs(wrap(lambda - lambdaOld)) + Math.abs(wrap(phi - phiOld));
+  const positive = solveFor(uxMagnitude);
+  const negative = solveFor(-uxMagnitude);
+  const best = distanceToCurrent(positive) <= distanceToCurrent(negative) ? positive : negative;
+  return [-best.lambda / DEG, -best.phi / DEG, roll];
+}
+
+/**
+ * Given the current d3 `rotate` `[lambda, phi, gamma]` (degrees), returns the
+ * `[longitude, latitude, roll]` that pans `geoPoint` toward the identity-frame screen coordinate
+ * `targetGeoPoint` along the longitude axis only: the latitude and roll are left untouched and just
+ * the longitude is solved so `geoPoint` reaches the target's longitude.
+ */
+function getLongitudeRotation(rotate, geoPoint, targetGeoPoint) {
+  const roll = rotate[2] ?? 0;
+  const latitude = -rotate[1]; // the fixed center latitude (degrees)
+
+  // Undo the roll on the target, then keep the pitch locked to the current latitude and solve the
+  // yaw so `geoPoint` lands on the target's longitude.
+  const [tx, ty, tz] = unitVector(rollCoordinate(targetGeoPoint, -roll));
+  const lonG = geoPoint[0] * DEG;
+  const c1 = latitude * DEG;
+  const c0 = lonG - Math.atan2(ty, tx * Math.cos(c1) - tz * Math.sin(c1));
+
+  // Normalize the longitude into `[-180, 180]`.
+  let longitude = c0 / DEG % 360;
+  if (longitude > 180) {
+    longitude -= 360;
+  } else if (longitude < -180) {
+    longitude += 360;
+  }
+  return [longitude, latitude, roll];
+}