@mui/x-charts-premium 9.8.0 → 9.10.0

package/internals/plugins/useGeoProjectionZoom/rotationMath.mjs

@@ -0,0 +1,182 @@
+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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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];
+}

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

@@ -0,0 +1,3 @@
+import type { ChartPlugin } from '@mui/x-charts/internals';
+import type { UseGeoProjectionZoomSignature } from "./useGeoProjectionZoom.types.mjs";
+export declare const useGeoProjectionZoom: ChartPlugin<UseGeoProjectionZoomSignature>;

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

@@ -0,0 +1,3 @@
+import type { ChartPlugin } from '@mui/x-charts/internals';
+import type { UseGeoProjectionZoomSignature } from "./useGeoProjectionZoom.types.js";
+export declare const useGeoProjectionZoom: ChartPlugin<UseGeoProjectionZoomSignature>;

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.js

@@ -0,0 +1,174 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useGeoProjectionZoom = void 0;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var React = _interopRequireWildcard(require("react"));
+var _useEffectAfterFirstRender = require("@mui/x-internals/useEffectAfterFirstRender");
+var _internals = require("@mui/x-charts-pro/internals");
+var _useGeoProjection = require("../useGeoProjection/useGeoProjection.selectors");
+var _mapZoom = require("./mapZoom.utils");
+var _usePanOnDrag = require("./gestureHooks/usePanOnDrag");
+var _useZoomOnWheel = require("./gestureHooks/useZoomOnWheel");
+var _useZoomOnPinch = require("./gestureHooks/useZoomOnPinch");
+var _projection = require("../useGeoProjection/projection.utils");
+const useGeoProjectionZoom = ({
+  store,
+  instance,
+  params
+}) => {
+  const {
+    zoom,
+    onViewChange,
+    view
+  } = params;
+  const interactionDefaults = (0, _mapZoom.getDefaultMapInteraction)((0, _useGeoProjection.selectorChartRawProjection)(store.state));
+  const {
+    minZoomLevel = 0.5,
+    maxZoomLevel = 8,
+    maxEmptySpace = 0,
+    rotationAllowed = interactionDefaults.rotationAllowed,
+    translationAllowed = interactionDefaults.translationAllowed
+  } = typeof zoom === 'object' ? zoom : {};
+
+  // `zoom` is either a boolean or a config object; an object always enables the interaction.
+  const enabled = zoom !== false;
+  const isControlled = view !== undefined;
+  const clampZoomLevel = React.useCallback(zoomLevel => Math.max(minZoomLevel, Math.min(maxZoomLevel, zoomLevel)), [minZoomLevel, maxZoomLevel]);
+
+  // The view is the source of truth, stored directly: no pixel <-> view conversion on write/read.
+  // Callers are responsible for clamping `zoomLevel`.
+  const applyView = React.useCallback(newView => {
+    if (!isControlled) {
+      store.set('geoProjectionZoom', (0, _extends2.default)({}, store.state.geoProjectionZoom, {
+        zoomLevel: newView.zoomLevel,
+        center: newView.center,
+        translation: newView.translation,
+        roll: newView.roll
+      }));
+    }
+    onViewChange?.(newView);
+  }, [store, isControlled, onViewChange]);
+
+  // In controlled mode, keep the store in sync with the `view` prop. The initial view is seeded in
+  // `getInitialState`, so this only reacts to subsequent updates.
+  (0, _useEffectAfterFirstRender.useEffectAfterFirstRender)(() => {
+    if (!view) {
+      return;
+    }
+    store.set('geoProjectionZoom', (0, _extends2.default)({}, store.state.geoProjectionZoom, {
+      zoomLevel: view.zoomLevel,
+      center: view.center,
+      translation: view.translation,
+      roll: view.roll
+    }));
+  }, [store, view]);
+  (0, _internals.useRegisterZoomGestures)({
+    instance
+  });
+
+  // --- gestures: reuse the generic primitives from x-charts-pro -------------
+  (0, _usePanOnDrag.usePanOnDrag)({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace
+  });
+  (0, _useZoomOnWheel.useZoomOnWheel)({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace,
+    minZoomLevel,
+    maxZoomLevel
+  });
+  (0, _useZoomOnPinch.useZoomOnPinch)({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace,
+    minZoomLevel,
+    maxZoomLevel
+  });
+
+  // Shared by both buttons: clamp through `applyView` (which also handles controlled mode and
+  // `onViewChange`), keeping the current center/translation. Bail out when already at a bound so a
+  // click at the limit stays a no-op.
+  const zoomBy = React.useCallback(factor => {
+    const current = store.state.geoProjectionZoom;
+    const currentZoom = current.zoomLevel ?? 1;
+    const nextZoom = clampZoomLevel(currentZoom * factor);
+    if (nextZoom === currentZoom) {
+      return;
+    }
+    applyView({
+      zoomLevel: nextZoom,
+      center: current.center ?? [0, 0],
+      translation: current.translation ?? [0, 0],
+      roll: current.roll ?? 0
+    });
+  }, [store, clampZoomLevel, applyView]);
+  const zoomIn = React.useCallback(() => zoomBy(_mapZoom.BUTTON_ZOOM_STEP), [zoomBy]);
+  const zoomOut = React.useCallback(() => zoomBy(1 / _mapZoom.BUTTON_ZOOM_STEP), [zoomBy]);
+  const resetZoom = React.useCallback(() => {
+    applyView({
+      zoomLevel: store.state.geoProjectionZoom.initialZoomLevel,
+      center: store.state.geoProjectionZoom.initialCenter,
+      translation: store.state.geoProjectionZoom.initialTranslation,
+      roll: store.state.geoProjectionZoom.initialRoll
+    });
+  }, [applyView, store]);
+  const publicAPI = {
+    zoomIn,
+    zoomOut,
+    resetZoom
+  };
+  return {
+    publicAPI,
+    instance: publicAPI
+  };
+};
+exports.useGeoProjectionZoom = useGeoProjectionZoom;
+useGeoProjectionZoom.params = {
+  zoom: true,
+  initialView: true,
+  view: true,
+  onViewChange: true
+};
+useGeoProjectionZoom.getDefaultizedParams = ({
+  params
+}) => (0, _extends2.default)({}, params, {
+  zoom: params.zoom ?? false
+});
+useGeoProjectionZoom.getInitialState = params => {
+  const zoomLevel = params.view?.zoomLevel ?? params.initialView?.zoomLevel ?? 1;
+  const center = params.view?.center ?? params.initialView?.center ?? [0, 0];
+  const roll = params.view?.roll ?? params.initialView?.roll ?? 0;
+  const translation = params.view?.translation ?? params.initialView?.translation ?? (0, _projection.getDefaultTranslation)(params.projection, params.geoData, params.parallels, center) ?? [0, 0];
+  return {
+    geoProjectionZoom: {
+      zoomLevel,
+      center,
+      translation,
+      roll,
+      initialZoomLevel: zoomLevel,
+      initialCenter: center,
+      initialTranslation: translation,
+      initialRoll: roll
+    }
+  };
+};

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.mjs

@@ -0,0 +1,166 @@
+'use client';
+
+import _extends from "@babel/runtime/helpers/esm/extends";
+import * as React from 'react';
+import { useEffectAfterFirstRender } from '@mui/x-internals/useEffectAfterFirstRender';
+import { useRegisterZoomGestures } from '@mui/x-charts-pro/internals';
+import { selectorChartRawProjection } from "../useGeoProjection/useGeoProjection.selectors.mjs";
+import { BUTTON_ZOOM_STEP, getDefaultMapInteraction } from "./mapZoom.utils.mjs";
+import { usePanOnDrag } from "./gestureHooks/usePanOnDrag.mjs";
+import { useZoomOnWheel } from "./gestureHooks/useZoomOnWheel.mjs";
+import { useZoomOnPinch } from "./gestureHooks/useZoomOnPinch.mjs";
+import { getDefaultTranslation } from "../useGeoProjection/projection.utils.mjs";
+export const useGeoProjectionZoom = ({
+  store,
+  instance,
+  params
+}) => {
+  const {
+    zoom,
+    onViewChange,
+    view
+  } = params;
+  const interactionDefaults = getDefaultMapInteraction(selectorChartRawProjection(store.state));
+  const {
+    minZoomLevel = 0.5,
+    maxZoomLevel = 8,
+    maxEmptySpace = 0,
+    rotationAllowed = interactionDefaults.rotationAllowed,
+    translationAllowed = interactionDefaults.translationAllowed
+  } = typeof zoom === 'object' ? zoom : {};
+
+  // `zoom` is either a boolean or a config object; an object always enables the interaction.
+  const enabled = zoom !== false;
+  const isControlled = view !== undefined;
+  const clampZoomLevel = React.useCallback(zoomLevel => Math.max(minZoomLevel, Math.min(maxZoomLevel, zoomLevel)), [minZoomLevel, maxZoomLevel]);
+
+  // The view is the source of truth, stored directly: no pixel <-> view conversion on write/read.
+  // Callers are responsible for clamping `zoomLevel`.
+  const applyView = React.useCallback(newView => {
+    if (!isControlled) {
+      store.set('geoProjectionZoom', _extends({}, store.state.geoProjectionZoom, {
+        zoomLevel: newView.zoomLevel,
+        center: newView.center,
+        translation: newView.translation,
+        roll: newView.roll
+      }));
+    }
+    onViewChange?.(newView);
+  }, [store, isControlled, onViewChange]);
+
+  // In controlled mode, keep the store in sync with the `view` prop. The initial view is seeded in
+  // `getInitialState`, so this only reacts to subsequent updates.
+  useEffectAfterFirstRender(() => {
+    if (!view) {
+      return;
+    }
+    store.set('geoProjectionZoom', _extends({}, store.state.geoProjectionZoom, {
+      zoomLevel: view.zoomLevel,
+      center: view.center,
+      translation: view.translation,
+      roll: view.roll
+    }));
+  }, [store, view]);
+  useRegisterZoomGestures({
+    instance
+  });
+
+  // --- gestures: reuse the generic primitives from x-charts-pro -------------
+  usePanOnDrag({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace
+  });
+  useZoomOnWheel({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace,
+    minZoomLevel,
+    maxZoomLevel
+  });
+  useZoomOnPinch({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace,
+    minZoomLevel,
+    maxZoomLevel
+  });
+
+  // Shared by both buttons: clamp through `applyView` (which also handles controlled mode and
+  // `onViewChange`), keeping the current center/translation. Bail out when already at a bound so a
+  // click at the limit stays a no-op.
+  const zoomBy = React.useCallback(factor => {
+    const current = store.state.geoProjectionZoom;
+    const currentZoom = current.zoomLevel ?? 1;
+    const nextZoom = clampZoomLevel(currentZoom * factor);
+    if (nextZoom === currentZoom) {
+      return;
+    }
+    applyView({
+      zoomLevel: nextZoom,
+      center: current.center ?? [0, 0],
+      translation: current.translation ?? [0, 0],
+      roll: current.roll ?? 0
+    });
+  }, [store, clampZoomLevel, applyView]);
+  const zoomIn = React.useCallback(() => zoomBy(BUTTON_ZOOM_STEP), [zoomBy]);
+  const zoomOut = React.useCallback(() => zoomBy(1 / BUTTON_ZOOM_STEP), [zoomBy]);
+  const resetZoom = React.useCallback(() => {
+    applyView({
+      zoomLevel: store.state.geoProjectionZoom.initialZoomLevel,
+      center: store.state.geoProjectionZoom.initialCenter,
+      translation: store.state.geoProjectionZoom.initialTranslation,
+      roll: store.state.geoProjectionZoom.initialRoll
+    });
+  }, [applyView, store]);
+  const publicAPI = {
+    zoomIn,
+    zoomOut,
+    resetZoom
+  };
+  return {
+    publicAPI,
+    instance: publicAPI
+  };
+};
+useGeoProjectionZoom.params = {
+  zoom: true,
+  initialView: true,
+  view: true,
+  onViewChange: true
+};
+useGeoProjectionZoom.getDefaultizedParams = ({
+  params
+}) => _extends({}, params, {
+  zoom: params.zoom ?? false
+});
+useGeoProjectionZoom.getInitialState = params => {
+  const zoomLevel = params.view?.zoomLevel ?? params.initialView?.zoomLevel ?? 1;
+  const center = params.view?.center ?? params.initialView?.center ?? [0, 0];
+  const roll = params.view?.roll ?? params.initialView?.roll ?? 0;
+  const translation = params.view?.translation ?? params.initialView?.translation ?? getDefaultTranslation(params.projection, params.geoData, params.parallels, center) ?? [0, 0];
+  return {
+    geoProjectionZoom: {
+      zoomLevel,
+      center,
+      translation,
+      roll,
+      initialZoomLevel: zoomLevel,
+      initialCenter: center,
+      initialTranslation: translation,
+      initialRoll: roll
+    }
+  };
+};

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

@@ -0,0 +1,152 @@
+import type { ChartPluginSignature } from '@mui/x-charts/internals';
+import type { UseGeoProjectionSignature } from "../useGeoProjection/useGeoProjection.types.mjs";
+/**
+ * Which rotation axes a pan/zoom gesture may move:
+ * - `'both'`: rotate freely along longitude and latitude, keeping the roll fixed.
+ * - `'longitude'`: rotate along longitude only (lock the north–south tilt).
+ * - `'none'`: lock every axis.
+ * - `'both+roll'`: rotate freely along longitude and latitude, and allow rolling the map around the center.
+ */
+export type MapRotationAxis = 'both' | 'longitude' | 'none' | 'both+roll';
+export type MapTranslationAxis = 'both' | 'x' | 'y' | 'none';
+/**
+ * Public, resolution-independent representation of the map view.
+ *
+ * Unlike the raw projection `scale`/`translate` (both in SVG pixels, tied to the drawing-area
+ * size), a view survives a resize: `zoomLevel` is a ratio and `center` is a geographic coordinate.
+ */
+export interface MapZoomView {
+  /**
+   * The zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * `1` means the whole dataset fits the drawing area; `2` means twice as close.
+   */
+  zoomLevel: number;
+  /**
+   * The geographic coordinate `[longitude, latitude]` displayed at the center of the drawing area.
+   */
+  center: [number, number];
+  /**
+   * The map translation in percentage of the drawing area.
+   */
+  translation: [number, number];
+  /**
+   * The roll of the map, in degrees.
+   * This spins the map around the point displayed at the center of the drawing area, independently
+   * of the `center` (which controls longitude/latitude).
+   */
+  roll: number;
+}
+/**
+ * Fine-grained configuration for the map zoom/pan interaction, passed as the `zoom` parameter
+ * instead of a plain `true`.
+ */
+export interface MapZoomOptions {
+  /**
+   * Which axes the map can be rotated along while panning or zooming.
+   * For example, `'longitude'` lets the map rotate east–west but locks the north–south tilt.
+   */
+  rotationAllowed?: MapRotationAxis;
+  /**
+   * Which axes the map can be translated along while panning or zooming.
+   * For example, `'y'` lets the map translate vertically but locks the horizontal movement.
+   */
+  translationAllowed?: MapTranslationAxis;
+  /**
+   * The minimum zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * @default 1
+   */
+  minZoomLevel?: number;
+  /**
+   * The maximum zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * @default 8
+   */
+  maxZoomLevel?: number;
+  /**
+   * The maximal space left empty while panning, expressed as a ratio of the drawing area size.
+   * For example:
+   * - `0` keeps the map's bounding box flush with (or covering) the drawing area.
+   * - `0.5` lets the user pan until at most half of the drawing area is empty on a given side.
+   * @default 0
+   */
+  maxEmptySpace?: number;
+}
+interface UseGeoProjectionZoomParameters {
+  /**
+   * If `true`, the map can be panned (drag) and zoomed (wheel / pinch).
+   * Pass a {@link MapZoomOptions} object to fine-tune the interaction, e.g. restrict rotation axes.
+   * @default false
+   */
+  zoom?: boolean | MapZoomOptions;
+  /**
+   * The view to apply on mount, when the zoom is not controlled.
+   * Use this to seed the map at a specific zoom level and center without controlling it.
+   */
+  initialView?: Omit<MapZoomView, 'translation' | 'roll'> & Partial<Pick<MapZoomView, 'translation' | 'roll'>>;
+  /**
+   * The view to display, in controlled mode.
+   * When set, the component does not update the view on its own — drive it from `onViewChange`.
+   */
+  view?: MapZoomView;
+  /**
+   * Callback fired when the map zoom or pan changes (including programmatic reset).
+   * @param {MapZoomView} view The new zoom level and geographic center.
+   */
+  onViewChange?: (view: MapZoomView) => void;
+}
+interface UseGeoProjectionZoomDefaultizedParameters extends UseGeoProjectionZoomParameters {
+  zoom: boolean | MapZoomOptions;
+}
+/**
+ * Imperative methods shared by the plugin `instance` and the public `apiRef`.
+ */
+interface UseGeoProjectionZoomPublicApi {
+  /**
+   * Zoom the map in by a fixed step, centered on the drawing area.
+   */
+  zoomIn: () => void;
+  /**
+   * Zoom the map out by a fixed step, centered on the drawing area.
+   */
+  zoomOut: () => void;
+  /**
+   * Reset the map to the default scale and translation that fit the data in the drawing area.
+   */
+  resetZoom: () => void;
+}
+interface UseGeoProjectionZoomInstance extends UseGeoProjectionZoomPublicApi {}
+export interface UseGeoProjectionZoomState {
+  geoProjectionZoom: {
+    /**
+     * The zoom level, as a multiple of the scale that fits the data in the drawing area.
+     * `null` (the default) and `1` both mean fit-to-data. The absolute projection scale is
+     * derived as `fitScale * zoomLevel`, so this stays valid across resizes.
+     */
+    zoomLevel: number;
+    /**
+     * The geographic coordinate `[longitude, latitude]` displayed at the center of the drawing area.
+     * `null` keeps the data centered (the fit center).
+     */
+    center: [number, number];
+    /**
+     * The map translation in percentage of the drawing area.
+     */
+    translation: [number, number] | null;
+    /**
+     * The roll of the map, in degrees. `null` keeps the map upright (no roll).
+     */
+    roll: number;
+    initialTranslation: [number, number];
+    initialCenter: [number, number];
+    initialZoomLevel: number;
+    initialRoll: number;
+  };
+}
+export type UseGeoProjectionZoomSignature = ChartPluginSignature<{
+  params: UseGeoProjectionZoomParameters;
+  defaultizedParams: UseGeoProjectionZoomDefaultizedParameters;
+  publicAPI: UseGeoProjectionZoomPublicApi;
+  instance: UseGeoProjectionZoomInstance;
+  state: UseGeoProjectionZoomState;
+  dependencies: [UseGeoProjectionSignature];
+}>;
+export {};