@mui/x-charts-premium 9.7.0 → 9.9.0

package/internals/plugins/useGeoProjectionZoom/gestureHooks/useZoomOnPinch.mjs

@@ -0,0 +1,56 @@
+'use client';
+
+import { usePinchGesture } from '@mui/x-charts-pro/internals';
+import { selectorChartProjection } from "../../useGeoProjection/index.mjs";
+import { getRotation, getTranslation } from "../mapZoom.utils.mjs";
+export const useZoomOnPinch = ({
+  store,
+  instance
+}, applyView, options) => {
+  const {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace
+  } = options;
+  const projection = store.use(selectorChartProjection);
+  const clampZoomLevel = zoomLevel => Math.max(options.minZoomLevel, Math.min(options.maxZoomLevel, zoomLevel));
+  usePinchGesture(instance, {
+    enabled,
+    onPinch: (point, deltaScale) => {
+      if (!projection || !projection.invert) {
+        return;
+      }
+
+      // Same clamp-then-derive-factor flow as the wheel, so pinch obeys the identical bounds.
+      const currentZoom = store.state.geoProjectionZoom.zoomLevel ?? 1;
+      const nextZoom = clampZoomLevel(currentZoom * (1 + deltaScale));
+      const factor = nextZoom / currentZoom;
+      if (factor === 1) {
+        return;
+      }
+      const geoPoint = projection.invert([point.x, point.y]);
+      if (!geoPoint) {
+        return;
+      }
+      const nextRotation = getRotation(projection, geoPoint, [point.x, point.y], factor, rotationAllowed);
+      const scale = projection.scale();
+      const rotate = projection.rotate?.();
+      if (nextRotation) {
+        projection.rotate?.([-nextRotation[0], -nextRotation[1], nextRotation[2]]);
+      }
+      projection.scale(scale * factor);
+      const translation = getTranslation(store, projection, geoPoint, [point.x, point.y], translationAllowed, maxEmptySpace, store.state.geoProjectionZoom.translation ?? [0, 0]);
+      projection.rotate?.(rotate);
+      projection.scale(scale);
+      if (nextRotation || translation) {
+        applyView({
+          zoomLevel: nextZoom,
+          center: nextRotation ? [nextRotation[0], nextRotation[1]] : store.state.geoProjectionZoom.center ?? [0, 0],
+          translation: translation ?? store.state.geoProjectionZoom.translation ?? [0, 0],
+          roll: nextRotation ? nextRotation[2] : store.state.geoProjectionZoom.roll ?? 0
+        });
+      }
+    }
+  });
+};

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

@@ -0,0 +1,13 @@
+import type { ChartPlugin } from '@mui/x-charts/internals';
+import type { MapRotationAxis, MapTranslationAxis, MapZoomView, UseGeoProjectionZoomSignature } from "../useGeoProjectionZoom.types.mjs";
+export declare const useZoomOnWheel: ({
+  store,
+  instance
+}: Pick<Parameters<ChartPlugin<UseGeoProjectionZoomSignature>>[0], "store" | "instance">, applyView: (newView: MapZoomView) => void, options: {
+  enabled: boolean;
+  rotationAllowed: MapRotationAxis;
+  translationAllowed: MapTranslationAxis;
+  maxEmptySpace: number;
+  minZoomLevel: number;
+  maxZoomLevel: number;
+}) => void;

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

@@ -0,0 +1,13 @@
+import type { ChartPlugin } from '@mui/x-charts/internals';
+import type { MapRotationAxis, MapTranslationAxis, MapZoomView, UseGeoProjectionZoomSignature } from "../useGeoProjectionZoom.types.js";
+export declare const useZoomOnWheel: ({
+  store,
+  instance
+}: Pick<Parameters<ChartPlugin<UseGeoProjectionZoomSignature>>[0], "store" | "instance">, applyView: (newView: MapZoomView) => void, options: {
+  enabled: boolean;
+  rotationAllowed: MapRotationAxis;
+  translationAllowed: MapTranslationAxis;
+  maxEmptySpace: number;
+  minZoomLevel: number;
+  maxZoomLevel: number;
+}) => void;

package/internals/plugins/useGeoProjectionZoom/gestureHooks/useZoomOnWheel.js

@@ -0,0 +1,64 @@
+"use strict";
+'use client';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useZoomOnWheel = void 0;
+var _internals = require("@mui/x-charts-pro/internals");
+var _useGeoProjection = require("../../useGeoProjection");
+var _mapZoom = require("../mapZoom.utils");
+const useZoomOnWheel = ({
+  store,
+  instance
+}, applyView, options) => {
+  const {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace
+  } = options;
+  const projection = store.use(_useGeoProjection.selectorChartProjection);
+  const clampZoomLevel = zoomLevel => Math.max(options.minZoomLevel, Math.min(options.maxZoomLevel, zoomLevel));
+  (0, _internals.useWheelGesture)(instance, {
+    enabled,
+    onWheel: (point, event) => {
+      if (!projection || !projection.invert) {
+        return;
+      }
+
+      // Clamp the target zoom first, then derive the factor actually applied. At the bounds the
+      // factor collapses to `1`, so wheeling further neither scales nor shifts the map.
+      const currentZoom = store.state.geoProjectionZoom.zoomLevel ?? 1;
+      const rawFactor = event.deltaY < 0 ? _mapZoom.WHEEL_ZOOM_STEP : 1 / _mapZoom.WHEEL_ZOOM_STEP;
+      const nextZoom = clampZoomLevel(currentZoom * rawFactor);
+      const factor = nextZoom / currentZoom;
+      if (factor === 1) {
+        return;
+      }
+      const geoPoint = projection.invert([point.x, point.y]);
+      if (!geoPoint) {
+        return;
+      }
+      const rotate = projection.rotate?.();
+      const scale = projection.scale();
+      const nextRotation = (0, _mapZoom.getRotation)(projection, geoPoint, [point.x, point.y], factor, rotationAllowed);
+      if (nextRotation) {
+        projection.rotate?.([-nextRotation[0], -nextRotation[1], nextRotation[2]]);
+      }
+      projection.scale(scale * factor);
+      const translation = (0, _mapZoom.getTranslation)(store, projection, geoPoint, [point.x, point.y], translationAllowed, maxEmptySpace);
+      projection.rotate?.(rotate);
+      projection.scale(scale);
+      if (nextRotation || translation) {
+        applyView({
+          zoomLevel: nextZoom,
+          center: nextRotation ? [nextRotation[0], nextRotation[1]] : store.state.geoProjectionZoom.center ?? [0, 0],
+          translation: translation ?? store.state.geoProjectionZoom.translation ?? [0, 0],
+          roll: nextRotation ? nextRotation[2] : store.state.geoProjectionZoom.roll ?? 0
+        });
+      }
+    }
+  });
+};
+exports.useZoomOnWheel = useZoomOnWheel;

package/internals/plugins/useGeoProjectionZoom/gestureHooks/useZoomOnWheel.mjs

@@ -0,0 +1,58 @@
+'use client';
+
+import { useWheelGesture } from '@mui/x-charts-pro/internals';
+import { selectorChartProjection } from "../../useGeoProjection/index.mjs";
+import { getRotation, getTranslation, WHEEL_ZOOM_STEP } from "../mapZoom.utils.mjs";
+export const useZoomOnWheel = ({
+  store,
+  instance
+}, applyView, options) => {
+  const {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace
+  } = options;
+  const projection = store.use(selectorChartProjection);
+  const clampZoomLevel = zoomLevel => Math.max(options.minZoomLevel, Math.min(options.maxZoomLevel, zoomLevel));
+  useWheelGesture(instance, {
+    enabled,
+    onWheel: (point, event) => {
+      if (!projection || !projection.invert) {
+        return;
+      }
+
+      // Clamp the target zoom first, then derive the factor actually applied. At the bounds the
+      // factor collapses to `1`, so wheeling further neither scales nor shifts the map.
+      const currentZoom = store.state.geoProjectionZoom.zoomLevel ?? 1;
+      const rawFactor = event.deltaY < 0 ? WHEEL_ZOOM_STEP : 1 / WHEEL_ZOOM_STEP;
+      const nextZoom = clampZoomLevel(currentZoom * rawFactor);
+      const factor = nextZoom / currentZoom;
+      if (factor === 1) {
+        return;
+      }
+      const geoPoint = projection.invert([point.x, point.y]);
+      if (!geoPoint) {
+        return;
+      }
+      const rotate = projection.rotate?.();
+      const scale = projection.scale();
+      const nextRotation = getRotation(projection, geoPoint, [point.x, point.y], factor, rotationAllowed);
+      if (nextRotation) {
+        projection.rotate?.([-nextRotation[0], -nextRotation[1], nextRotation[2]]);
+      }
+      projection.scale(scale * factor);
+      const translation = getTranslation(store, projection, geoPoint, [point.x, point.y], translationAllowed, maxEmptySpace);
+      projection.rotate?.(rotate);
+      projection.scale(scale);
+      if (nextRotation || translation) {
+        applyView({
+          zoomLevel: nextZoom,
+          center: nextRotation ? [nextRotation[0], nextRotation[1]] : store.state.geoProjectionZoom.center ?? [0, 0],
+          translation: translation ?? store.state.geoProjectionZoom.translation ?? [0, 0],
+          roll: nextRotation ? nextRotation[2] : store.state.geoProjectionZoom.roll ?? 0
+        });
+      }
+    }
+  });
+};

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

@@ -0,0 +1,2 @@
+export { useGeoProjectionZoom } from "./useGeoProjectionZoom.mjs";
+export type { UseGeoProjectionZoomSignature, MapZoomView } from "./useGeoProjectionZoom.types.mjs";

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

@@ -0,0 +1,2 @@
+export { useGeoProjectionZoom } from "./useGeoProjectionZoom.js";
+export type { UseGeoProjectionZoomSignature, MapZoomView } from "./useGeoProjectionZoom.types.js";

package/internals/plugins/useGeoProjectionZoom/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "useGeoProjectionZoom", {
+  enumerable: true,
+  get: function () {
+    return _useGeoProjectionZoom.useGeoProjectionZoom;
+  }
+});
+var _useGeoProjectionZoom = require("./useGeoProjectionZoom");

package/internals/plugins/useGeoProjectionZoom/index.mjs

@@ -0,0 +1 @@
+export { useGeoProjectionZoom } from "./useGeoProjectionZoom.mjs";

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

@@ -0,0 +1,31 @@
+import type { GeoProjection } from '@mui/x-charts-vendor/d3-geo';
+import type { ChartUsedStore } from '@mui/x-charts/internals';
+import type { MapRotationAxis, MapTranslationAxis } from "./useGeoProjectionZoom.types.mjs";
+import type { GeoProjectionInput } from "../useGeoProjection/index.mjs";
+/** Multiplicative zoom step applied per wheel tick. */
+export declare const WHEEL_ZOOM_STEP = 1.1;
+/** Multiplicative zoom step applied per `zoomIn`/`zoomOut` call. */
+export declare const BUTTON_ZOOM_STEP = 1.3;
+type ProjectionFamily = 'azimuthal' | 'conic' | 'cylindrical' | 'albersUsa';
+export declare function getProjectionFamily(projection: GeoProjectionInput | null): ProjectionFamily;
+export declare function getDefaultMapInteraction(projection: GeoProjectionInput | null): {
+  rotationAllowed: MapRotationAxis;
+  translationAllowed: MapTranslationAxis;
+};
+/**
+ * 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 declare function getRotation(projection: GeoProjection, geoPoint: [number, number], to: [number, number], zoomFactor?: number, rotationAllowed?: MapRotationAxis): [number, number, number] | null;
+export declare function clampTranslationAxis(value: number, init: number, boundingBox0: number, boundingBox1: number, areaStart: number, areaEnd: number, gap: number): number;
+export declare function getTranslation(store: ChartUsedStore<any>, projection: GeoProjection, geoPoint: [number, number], to: [number, number], translationAllowed?: MapTranslationAxis, maxEmptySpace?: number, currentTranslation?: [number, number]): [number, number] | null;
+export {};

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

@@ -0,0 +1,31 @@
+import type { GeoProjection } from '@mui/x-charts-vendor/d3-geo';
+import type { ChartUsedStore } from '@mui/x-charts/internals';
+import type { MapRotationAxis, MapTranslationAxis } from "./useGeoProjectionZoom.types.js";
+import type { GeoProjectionInput } from "../useGeoProjection/index.js";
+/** Multiplicative zoom step applied per wheel tick. */
+export declare const WHEEL_ZOOM_STEP = 1.1;
+/** Multiplicative zoom step applied per `zoomIn`/`zoomOut` call. */
+export declare const BUTTON_ZOOM_STEP = 1.3;
+type ProjectionFamily = 'azimuthal' | 'conic' | 'cylindrical' | 'albersUsa';
+export declare function getProjectionFamily(projection: GeoProjectionInput | null): ProjectionFamily;
+export declare function getDefaultMapInteraction(projection: GeoProjectionInput | null): {
+  rotationAllowed: MapRotationAxis;
+  translationAllowed: MapTranslationAxis;
+};
+/**
+ * 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 declare function getRotation(projection: GeoProjection, geoPoint: [number, number], to: [number, number], zoomFactor?: number, rotationAllowed?: MapRotationAxis): [number, number, number] | null;
+export declare function clampTranslationAxis(value: number, init: number, boundingBox0: number, boundingBox1: number, areaStart: number, areaEnd: number, gap: number): number;
+export declare function getTranslation(store: ChartUsedStore<any>, projection: GeoProjection, geoPoint: [number, number], to: [number, number], translationAllowed?: MapTranslationAxis, maxEmptySpace?: number, currentTranslation?: [number, number]): [number, number] | null;
+export {};

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];
+}