@accelint/map-toolkit 0.4.0 → 0.5.0

package/dist/camera/use-camera-state.js

@@ -0,0 +1,419 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { CameraEventTypes } from "./events.js";
+import { fitBounds } from "../node_modules/.pnpm/@math.gl_web-mercator@4.1.0/node_modules/@math.gl/web-mercator/dist/fit-bounds.js";
+import "../node_modules/.pnpm/@math.gl_web-mercator@4.1.0/node_modules/@math.gl/web-mercator/dist/index.js";
+import { Broadcast } from "@accelint/bus";
+import { useMemo, useSyncExternalStore } from "react";
+
+//#region src/camera/use-camera-state.ts
+/**
+* Typed event bus instance for camera events.
+* Provides type-safe event emission and listening for all camera state changes.
+*/
+const cameraBus = Broadcast.getInstance();
+/**
+* Store for camera state keyed by instanceId
+*/
+const cameraStore = /* @__PURE__ */ new Map();
+/**
+* Track React component subscribers per instanceId (for fan-out notifications).
+* Each Set contains onStoreChange callbacks from useSyncExternalStore.
+*/
+const componentSubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of bus unsubscribe functions (1 per instanceId).
+* This ensures we only have one bus listener per camera, regardless of
+* how many React components subscribe to it.
+*/
+const busUnsubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of subscription functions per instanceId to avoid recreating on every render
+*/
+const subscriptionCache = /* @__PURE__ */ new Map();
+/**
+* Cache of snapshot functions per instanceId to maintain referential stability
+*/
+const snapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of fallback snapshots per instanceId to maintain referential stability.
+* This prevents unnecessary re-renders when no camera data exists yet.
+*/
+const fallbackCache = /* @__PURE__ */ new Map();
+function buildInitialCameraState(initialCameraState) {
+	if (!initialCameraState) return {
+		latitude: 0,
+		longitude: 0,
+		zoom: 0,
+		pitch: 0,
+		rotation: 0,
+		projection: "mercator",
+		view: "2D"
+	};
+	const is2Point5D = initialCameraState.view === "2.5D";
+	const is3D = initialCameraState.view === "3D" || initialCameraState.projection === "globe";
+	let projection;
+	let view;
+	if (is3D) {
+		projection = "globe";
+		view = "3D";
+	} else if (is2Point5D) {
+		projection = "mercator";
+		view = "2.5D";
+	} else {
+		projection = initialCameraState.projection ?? "mercator";
+		view = initialCameraState.view ?? "2D";
+	}
+	return {
+		latitude: initialCameraState.latitude ?? 0,
+		longitude: initialCameraState.longitude ?? 0,
+		zoom: initialCameraState.zoom ?? 0,
+		pitch: is2Point5D ? initialCameraState.pitch ?? 45 : 0,
+		rotation: is3D ? 0 : initialCameraState.rotation ?? 0,
+		projection,
+		view
+	};
+}
+function getOrCreateState(instanceId, initialCameraState) {
+	if (!cameraStore.has(instanceId)) cameraStore.set(instanceId, buildInitialCameraState(initialCameraState));
+	return cameraStore.get(instanceId);
+}
+/**
+* Notify all React subscribers for a given instanceId
+*/
+function notifySubscribers(instanceId) {
+	const subscribers = componentSubscribers.get(instanceId);
+	if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
+}
+/**
+* Ensures a single bus listener exists for the given instanceId.
+* All React subscribers will be notified via fan-out when the bus event fires.
+* This prevents creating N bus listeners for N React components.
+*
+* @param instanceId - The unique identifier for the camera
+* @param initialCameraState - Optional initial camera state to set when creating the listener
+*/
+function ensureBusListener(instanceId, initialCameraState) {
+	if (busUnsubscribers.has(instanceId)) return;
+	const unsubResetCamera = cameraBus.on(CameraEventTypes.reset, ({ payload }) => {
+		if (instanceId === payload.id) {
+			const state = getOrCreateState(instanceId, initialCameraState);
+			const newState = { ...buildInitialCameraState({
+				...state,
+				zoom: payload.zoom === false ? state.zoom : initialCameraState?.zoom,
+				pitch: payload.pitch === false ? state.pitch : initialCameraState?.pitch,
+				rotation: payload.rotation === false ? state.rotation : initialCameraState?.rotation
+			}) };
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubSetCenter = cameraBus.on(CameraEventTypes.setCenter, ({ payload }) => {
+		if (instanceId === payload.id) {
+			const state = getOrCreateState(instanceId, initialCameraState);
+			const newState = {
+				...state,
+				latitude: payload.latitude,
+				longitude: payload.longitude,
+				zoom: payload.zoom ?? state.zoom,
+				rotation: payload.heading ?? state.rotation,
+				pitch: payload.pitch ?? state.pitch
+			};
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubFitBounds = cameraBus.on(CameraEventTypes.fitBounds, ({ payload }) => {
+		if (instanceId === payload.id) {
+			const state = getOrCreateState(instanceId, initialCameraState);
+			const { longitude, latitude, zoom } = fitBounds({
+				width: payload.width,
+				height: payload.height,
+				bounds: [[payload.bounds[0], payload.bounds[1]], [payload.bounds[2], payload.bounds[3]]],
+				padding: payload.padding
+			});
+			const newState = {
+				...state,
+				latitude,
+				longitude,
+				zoom,
+				rotation: payload.heading ?? state.rotation,
+				pitch: payload.pitch ?? state.pitch
+			};
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubSetProjection = cameraBus.on(CameraEventTypes.setProjection, ({ payload }) => {
+		if (instanceId === payload.id) {
+			const newState = { ...getOrCreateState(instanceId, initialCameraState) };
+			newState.projection = payload.projection;
+			if (payload.projection === "globe") newState.view = "3D";
+			else {
+				newState.view = "2D";
+				newState.pitch = 0;
+			}
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubSetView = cameraBus.on(CameraEventTypes.setView, ({ payload }) => {
+		if (instanceId === payload.id) {
+			const newState = { ...getOrCreateState(instanceId, initialCameraState) };
+			newState.view = payload.view;
+			if (payload.view === "3D") {
+				newState.projection = "globe";
+				newState.pitch = 0;
+			} else newState.projection = "mercator";
+			if (payload.view === "2.5D") newState.pitch = 45;
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubSetZoom = cameraBus.on(CameraEventTypes.setZoom, ({ payload }) => {
+		if (instanceId === payload.id) {
+			const newState = { ...getOrCreateState(instanceId, initialCameraState) };
+			newState.zoom = payload.zoom;
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubSetRotation = cameraBus.on(CameraEventTypes.setRotation, ({ payload }) => {
+		const state = getOrCreateState(instanceId, initialCameraState);
+		if (instanceId === payload.id && state.view !== "3D") {
+			const newState = { ...state };
+			newState.rotation = payload.rotation;
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	const unsubSetPitch = cameraBus.on(CameraEventTypes.setPitch, ({ payload }) => {
+		const state = getOrCreateState(instanceId, initialCameraState);
+		if (instanceId === payload.id && state.view === "2.5D") {
+			const newState = { ...state };
+			newState.pitch = payload.pitch;
+			cameraStore.set(instanceId, newState);
+			notifySubscribers(instanceId);
+		}
+	});
+	busUnsubscribers.set(instanceId, () => {
+		unsubResetCamera();
+		unsubSetCenter();
+		unsubFitBounds();
+		unsubSetProjection();
+		unsubSetView();
+		unsubSetZoom();
+		unsubSetRotation();
+		unsubSetPitch();
+	});
+}
+/**
+* Cleans up the bus listener if no React subscribers remain.
+*
+* @param instanceId - The unique identifier for the camera
+*/
+function cleanupBusListenerIfNeeded(instanceId) {
+	const subscribers = componentSubscribers.get(instanceId);
+	if (!subscribers || subscribers.size === 0) {
+		const unsub = busUnsubscribers.get(instanceId);
+		if (unsub) {
+			unsub();
+			busUnsubscribers.delete(instanceId);
+		}
+		[
+			cameraStore,
+			componentSubscribers,
+			subscriptionCache,
+			snapshotCache,
+			fallbackCache
+		].forEach((map) => {
+			map.delete(instanceId);
+		});
+	}
+}
+/**
+* Creates or retrieves a cached subscription function for a given instanceId.
+* Uses a fan-out pattern: 1 bus listener -> N React subscribers.
+* Automatically cleans up camera state when the last subscriber unsubscribes.
+*
+* @param instanceId - The unique identifier for the camera
+* @param initialCameraState - Optional initial camera state to set when creating the listener
+* @returns A subscription function for useSyncExternalStore
+*/
+function getOrCreateSubscription(instanceId, initialCameraState) {
+	const subscription = subscriptionCache.get(instanceId) ?? ((onStoreChange) => {
+		ensureBusListener(instanceId, initialCameraState);
+		let subscriberSet = componentSubscribers.get(instanceId);
+		if (!subscriberSet) {
+			subscriberSet = /* @__PURE__ */ new Set();
+			componentSubscribers.set(instanceId, subscriberSet);
+		}
+		subscriberSet.add(onStoreChange);
+		return () => {
+			const currentSubscriberSet = componentSubscribers.get(instanceId);
+			if (currentSubscriberSet) currentSubscriberSet.delete(onStoreChange);
+			cleanupBusListenerIfNeeded(instanceId);
+		};
+	});
+	subscriptionCache.set(instanceId, subscription);
+	return subscription;
+}
+/**
+* Creates or retrieves a cached snapshot function for a given instanceId.
+* The object returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
+*
+* @param instanceId - The unique identifier for the camera
+* @param initialCameraState - Initialize the snapshot with camera view information
+* @returns A snapshot function for useSyncExternalStore
+*/
+function getOrCreateSnapshot(instanceId, initialCameraState) {
+	const fallback = fallbackCache.get(instanceId) ?? (() => {
+		const newFallback = {
+			latitude: initialCameraState?.latitude ?? 0,
+			longitude: initialCameraState?.longitude ?? 0,
+			zoom: initialCameraState?.zoom ?? 0,
+			pitch: 0,
+			rotation: 0,
+			projection: "mercator",
+			view: "2D"
+		};
+		fallbackCache.set(instanceId, newFallback);
+		return newFallback;
+	})();
+	const snapshot = snapshotCache.get(instanceId) ?? (() => cameraStore.get(instanceId) ?? fallback);
+	snapshotCache.set(instanceId, snapshot);
+	return snapshot;
+}
+/**
+* Updates the camera state for a given map instance and notifies subscribers.
+*
+* @param instanceId - The unique identifier for the map
+* @param state - The new state to set, will be merged with existing state
+*
+* @example
+* ```tsx
+* // Update camera state manually
+* setCameraState('my-map-instance', {
+*   latitude: 37.7749,
+*   longitude: -122.4194,
+*   zoom: 10,
+*   pitch: 30,
+*   rotation: 0,
+*   projection: 'mercator',
+* });
+* ```
+*/
+function setCameraState(instanceId, state) {
+	const currentState = getOrCreateState(instanceId);
+	cameraStore.set(instanceId, {
+		...currentState,
+		...state
+	});
+	notifySubscribers(instanceId);
+}
+/**
+* Hook to access camera state actions.
+*
+* This hook uses `useSyncExternalStore` to subscribe to camera state changes,
+* providing concurrent-safe mode state updates. Uses a fan-out pattern where
+* a single bus listener per map instance notifies N React component subscribers.
+*
+* A thin wrapper around [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore).
+*
+* @param instanceId - Unique identifier for the camera to track
+* @param initialCameraState - Optional initial camera state to set
+* @param subscribe - Optional custom subscription function
+* @param getSnapshot - Optional custom snapshot getter
+* @param getServerSnapshot - Optional server-side snapshot getter
+* @returns Current camera state including latitude, longitude, zoom, pitch, rotation, projection
+*
+* @example
+* ```tsx
+* function MapInfo({ instanceId }) {
+*   const { latitude, longitude, zoom } = useCameraState({
+*     instanceId
+*   });
+*
+*   return (
+*     <div>
+*       Lat: {latitude?.toFixed(2)}, Lon: {longitude?.toFixed(2)}, Zoom: {zoom}
+*     </div>
+*   );
+* }
+* ```
+*
+* @example
+* ```tsx
+* // With custom subscribe/getSnapshot for advanced use cases
+* function CustomMapInfo() {
+*   const customSubscribe = (onStoreChange) => {
+*     // Custom subscription logic
+*     return () => { // cleanup }
+*   }
+*
+*   const customGetSnapshot = () => {
+*     // Custom snapshot logic
+*     return { latitude: 0, longitude: 0, zoom: 1 };
+*   };
+*
+*   const viewState = useCameraState({
+*     instanceId: 'some-uuid',
+*     subscribe: customSubscribe,
+*     getSnapshot: customGetSnapshot,
+*   });
+*
+*   return <div>Custom camera state</div>;
+* }
+* ```
+*/
+function useCameraState({ instanceId, initialCameraState, subscribe, getSnapshot, getServerSnapshot }) {
+	const cameraState = useSyncExternalStore(subscribe ?? getOrCreateSubscription(instanceId, initialCameraState), getSnapshot ?? getOrCreateSnapshot(instanceId, initialCameraState), getServerSnapshot);
+	return useMemo(() => ({
+		cameraState,
+		setCameraState
+	}), [cameraState]);
+}
+/**
+* Manually clear camera state for a specific instanceId.
+* This is typically not needed as cleanup happens automatically when all subscribers unmount.
+* Use this only in advanced scenarios where manual cleanup is required.
+*
+* @param instanceId - The unique identifier for the camera to clear
+*
+* @example
+* ```tsx
+* // Manual cleanup (rarely needed)
+* clearCameraState('my-map-instance');
+* ```
+*/
+function clearCameraState(instanceId) {
+	const unsub = busUnsubscribers.get(instanceId);
+	if (unsub) {
+		unsub();
+		busUnsubscribers.delete(instanceId);
+	}
+	[
+		cameraStore,
+		componentSubscribers,
+		subscriptionCache,
+		snapshotCache,
+		fallbackCache
+	].forEach((map) => {
+		map.delete(instanceId);
+	});
+}
+
+//#endregion
+export { clearCameraState, useCameraState };
+//# sourceMappingURL=use-camera-state.js.map

package/dist/camera/use-camera-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-camera-state.js","names":["projection: ProjectionType","view: ViewType","newFallback: CameraState"],"sources":["../../src/camera/use-camera-state.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { fitBounds } from '@math.gl/web-mercator';\nimport { useMemo, useSyncExternalStore } from 'react';\nimport { CameraEventTypes } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { CameraEvent, ProjectionType, ViewType } from './types';\n\n/**\n * Typed event bus instance for camera events.\n * Provides type-safe event emission and listening for all camera state changes.\n */\nconst cameraBus = Broadcast.getInstance<CameraEvent>();\n\ntype CameraState2D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'mercator';\n  view: '2D';\n};\n\ntype CameraState3D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'globe';\n  view: '3D';\n};\n\ntype CameraState2Point5D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: number;\n  rotation: number;\n  projection: 'mercator';\n  view: '2.5D';\n};\n\nexport type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;\n\nexport type UseCameraStateProps = {\n  instanceId: UniqueId;\n  initialCameraState?: Partial<CameraState>;\n  subscribe?: Parameters<typeof useSyncExternalStore<CameraState>>[0];\n  getSnapshot?: Parameters<typeof useSyncExternalStore<CameraState>>[1];\n  getServerSnapshot?: Parameters<typeof useSyncExternalStore<CameraState>>[2];\n};\n\n/**\n * Store for camera state keyed by instanceId\n */\nconst cameraStore = new Map<UniqueId, CameraState>();\n\n/**\n * Track React component subscribers per instanceId (for fan-out notifications).\n * Each Set contains onStoreChange callbacks from useSyncExternalStore.\n */\nconst componentSubscribers = new Map<UniqueId, Set<() => void>>();\n\n/**\n * Cache of bus unsubscribe functions (1 per instanceId).\n * This ensures we only have one bus listener per camera, regardless of\n * how many React components subscribe to it.\n */\nconst busUnsubscribers = new Map<UniqueId, () => void>();\n\ntype Subscription = (onStoreChange: () => void) => () => void;\n/**\n * Cache of subscription functions per instanceId to avoid recreating on every render\n */\nconst subscriptionCache = new Map<UniqueId, Subscription>();\n\n/**\n * Cache of snapshot functions per instanceId to maintain referential stability\n */\nconst snapshotCache = new Map<UniqueId, () => CameraState>();\n\n/**\n * Cache of fallback snapshots per instanceId to maintain referential stability.\n * This prevents unnecessary re-renders when no camera data exists yet.\n */\nconst fallbackCache = new Map<UniqueId, CameraState>();\n\n/*\n * Helper to build initial camera state from partial input\n */\nfunction buildInitialCameraState(\n  initialCameraState?: Partial<CameraState>,\n): CameraState {\n  if (!initialCameraState) {\n    return {\n      latitude: 0,\n      longitude: 0,\n      zoom: 0,\n      pitch: 0,\n      rotation: 0,\n      projection: 'mercator',\n      view: '2D',\n    };\n  }\n\n  const is2Point5D = initialCameraState.view === '2.5D';\n  const is3D =\n    initialCameraState.view === '3D' ||\n    initialCameraState.projection === 'globe';\n\n  let projection: ProjectionType;\n  let view: ViewType;\n\n  if (is3D) {\n    projection = 'globe';\n    view = '3D';\n  } else if (is2Point5D) {\n    projection = 'mercator';\n    view = '2.5D';\n  } else {\n    projection = initialCameraState.projection ?? 'mercator';\n    view = initialCameraState.view ?? '2D';\n  }\n\n  return {\n    latitude: initialCameraState.latitude ?? 0,\n    longitude: initialCameraState.longitude ?? 0,\n    zoom: initialCameraState.zoom ?? 0,\n    pitch: is2Point5D ? (initialCameraState.pitch ?? 45) : 0,\n    rotation: is3D ? 0 : (initialCameraState.rotation ?? 0),\n    projection,\n    view,\n  } as CameraState;\n}\n\n/*\n * Get or create camera state for a given instanceId\n */\nfunction getOrCreateState(\n  instanceId: UniqueId,\n  initialCameraState?: Partial<CameraState>,\n): CameraState {\n  if (!cameraStore.has(instanceId)) {\n    cameraStore.set(instanceId, buildInitialCameraState(initialCameraState));\n  }\n  // biome-ignore lint/style/noNonNullAssertion: State guaranteed to exist after has() check above\n  return cameraStore.get(instanceId)!;\n}\n\n/**\n * Notify all React subscribers for a given instanceId\n */\nfunction notifySubscribers(instanceId: UniqueId): void {\n  const subscribers = componentSubscribers.get(instanceId);\n\n  if (subscribers) {\n    for (const onStoreChange of subscribers) {\n      onStoreChange();\n    }\n  }\n}\n\n/**\n * Ensures a single bus listener exists for the given instanceId.\n * All React subscribers will be notified via fan-out when the bus event fires.\n * This prevents creating N bus listeners for N React components.\n *\n * @param instanceId - The unique identifier for the camera\n * @param initialCameraState - Optional initial camera state to set when creating the listener\n */\nfunction ensureBusListener(\n  instanceId: UniqueId,\n  initialCameraState?: Partial<CameraState>,\n): void {\n  if (busUnsubscribers.has(instanceId)) {\n    return; // Already listening\n  }\n\n  const unsubResetCamera = cameraBus.on(\n    CameraEventTypes.reset,\n    ({ payload }) => {\n      if (instanceId === payload.id) {\n        const state = getOrCreateState(instanceId, initialCameraState);\n        const newState = {\n          ...buildInitialCameraState({\n            ...state,\n            zoom:\n              payload.zoom === false ? state.zoom : initialCameraState?.zoom,\n            pitch:\n              payload.pitch === false ? state.pitch : initialCameraState?.pitch,\n            rotation:\n              payload.rotation === false\n                ? state.rotation\n                : initialCameraState?.rotation,\n          } as Partial<CameraState>),\n        };\n\n        cameraStore.set(instanceId, newState);\n\n        notifySubscribers(instanceId);\n      }\n    },\n  );\n\n  const unsubSetCenter = cameraBus.on(\n    CameraEventTypes.setCenter,\n    ({ payload }) => {\n      if (instanceId === payload.id) {\n        const state = getOrCreateState(instanceId, initialCameraState);\n        const newState = {\n          ...state,\n          latitude: payload.latitude,\n          longitude: payload.longitude,\n          zoom: payload.zoom ?? state.zoom,\n          rotation: payload.heading ?? state.rotation,\n          pitch: payload.pitch ?? state.pitch,\n        } as CameraState;\n        cameraStore.set(instanceId, newState);\n        notifySubscribers(instanceId);\n      }\n    },\n  );\n\n  const unsubFitBounds = cameraBus.on(\n    CameraEventTypes.fitBounds,\n    ({ payload }) => {\n      if (instanceId === payload.id) {\n        const state = getOrCreateState(instanceId, initialCameraState);\n        const { longitude, latitude, zoom } = fitBounds({\n          width: payload.width,\n          height: payload.height,\n          bounds: [\n            [payload.bounds[0], payload.bounds[1]],\n            [payload.bounds[2], payload.bounds[3]],\n          ],\n          padding: payload.padding,\n        });\n        const newState = {\n          ...state,\n          latitude: latitude,\n          longitude: longitude,\n          zoom: zoom,\n          rotation: payload.heading ?? state.rotation,\n          pitch: payload.pitch ?? state.pitch,\n        } as CameraState;\n        cameraStore.set(instanceId, newState);\n        notifySubscribers(instanceId);\n      }\n    },\n  );\n\n  const unsubSetProjection = cameraBus.on(\n    CameraEventTypes.setProjection,\n    ({ payload }) => {\n      if (instanceId === payload.id) {\n        const state = getOrCreateState(instanceId, initialCameraState);\n        const newState = { ...state };\n        newState.projection = payload.projection;\n        if (payload.projection === 'globe') {\n          newState.view = '3D';\n        } else {\n          newState.view = '2D';\n          newState.pitch = 0;\n        }\n        cameraStore.set(instanceId, newState);\n        notifySubscribers(instanceId);\n      }\n    },\n  );\n\n  const unsubSetView = cameraBus.on(CameraEventTypes.setView, ({ payload }) => {\n    if (instanceId === payload.id) {\n      const state = getOrCreateState(instanceId, initialCameraState);\n      const newState = { ...state };\n      newState.view = payload.view;\n      if (payload.view === '3D') {\n        newState.projection = 'globe';\n        newState.pitch = 0;\n      } else {\n        newState.projection = 'mercator';\n      }\n\n      if (payload.view === '2.5D') {\n        newState.pitch = 45;\n      }\n      cameraStore.set(instanceId, newState);\n      notifySubscribers(instanceId);\n    }\n  });\n\n  const unsubSetZoom = cameraBus.on(CameraEventTypes.setZoom, ({ payload }) => {\n    if (instanceId === payload.id) {\n      const state = getOrCreateState(instanceId, initialCameraState);\n      const newState = { ...state };\n      newState.zoom = payload.zoom;\n      cameraStore.set(instanceId, newState);\n      notifySubscribers(instanceId);\n    }\n  });\n\n  const unsubSetRotation = cameraBus.on(\n    CameraEventTypes.setRotation,\n    ({ payload }) => {\n      const state = getOrCreateState(instanceId, initialCameraState);\n      if (instanceId === payload.id && state.view !== '3D') {\n        const newState = { ...state };\n        newState.rotation = payload.rotation;\n        cameraStore.set(instanceId, newState);\n        notifySubscribers(instanceId);\n      }\n    },\n  );\n\n  const unsubSetPitch = cameraBus.on(\n    CameraEventTypes.setPitch,\n    ({ payload }) => {\n      const state = getOrCreateState(instanceId, initialCameraState);\n      if (instanceId === payload.id && state.view === '2.5D') {\n        const newState = { ...state };\n        newState.pitch = payload.pitch;\n        cameraStore.set(instanceId, newState);\n        notifySubscribers(instanceId);\n      }\n    },\n  );\n\n  busUnsubscribers.set(instanceId, () => {\n    unsubResetCamera();\n    unsubSetCenter();\n    unsubFitBounds();\n    unsubSetProjection();\n    unsubSetView();\n    unsubSetZoom();\n    unsubSetRotation();\n    unsubSetPitch();\n  });\n}\n\n/**\n * Cleans up the bus listener if no React subscribers remain.\n *\n * @param instanceId - The unique identifier for the camera\n */\nfunction cleanupBusListenerIfNeeded(instanceId: UniqueId): void {\n  const subscribers = componentSubscribers.get(instanceId);\n\n  if (!subscribers || subscribers.size === 0) {\n    // No more React subscribers - clean up bus listener\n    const unsub = busUnsubscribers.get(instanceId);\n    if (unsub) {\n      unsub();\n      busUnsubscribers.delete(instanceId);\n    }\n\n    // Clean up all state\n    [\n      cameraStore,\n      componentSubscribers,\n      subscriptionCache,\n      snapshotCache,\n      fallbackCache,\n    ].forEach((map) => {\n      map.delete(instanceId);\n    });\n  }\n}\n\n/**\n * Creates or retrieves a cached subscription function for a given instanceId.\n * Uses a fan-out pattern: 1 bus listener -> N React subscribers.\n * Automatically cleans up camera state when the last subscriber unsubscribes.\n *\n * @param instanceId - The unique identifier for the camera\n * @param initialCameraState - Optional initial camera state to set when creating the listener\n * @returns A subscription function for useSyncExternalStore\n */\nfunction getOrCreateSubscription(\n  instanceId: UniqueId,\n  initialCameraState?: Partial<CameraState>,\n): (onStoreChange: () => void) => () => void {\n  const subscription =\n    subscriptionCache.get(instanceId) ??\n    ((onStoreChange: () => void) => {\n      // Ensure single bus listener exists for this instanceId\n      ensureBusListener(instanceId, initialCameraState);\n\n      // Get or create the subscriber set for this map instance, then add this component's callback\n      let subscriberSet = componentSubscribers.get(instanceId);\n      if (!subscriberSet) {\n        subscriberSet = new Set();\n        componentSubscribers.set(instanceId, subscriberSet);\n      }\n      subscriberSet.add(onStoreChange);\n\n      // Return cleanup function to remove this component's subscription\n      return () => {\n        const currentSubscriberSet = componentSubscribers.get(instanceId);\n        if (currentSubscriberSet) {\n          currentSubscriberSet.delete(onStoreChange);\n        }\n\n        // Clean up bus listener if this was the last React subscriber\n        cleanupBusListenerIfNeeded(instanceId);\n      };\n    });\n\n  subscriptionCache.set(instanceId, subscription);\n\n  return subscription;\n}\n\n/**\n * Creates or retrieves a cached snapshot function for a given instanceId.\n * The object returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.\n *\n * @param instanceId - The unique identifier for the camera\n * @param initialCameraState - Initialize the snapshot with camera view information\n * @returns A snapshot function for useSyncExternalStore\n */\nfunction getOrCreateSnapshot(\n  instanceId: UniqueId,\n  initialCameraState?: Partial<CameraState>,\n): () => CameraState {\n  // Get or create stable fallback reference for this instanceId\n  const fallback =\n    fallbackCache.get(instanceId) ??\n    (() => {\n      const newFallback: CameraState = {\n        latitude: initialCameraState?.latitude ?? 0,\n        longitude: initialCameraState?.longitude ?? 0,\n        zoom: initialCameraState?.zoom ?? 0,\n        pitch: 0,\n        rotation: 0,\n        projection: 'mercator',\n        view: '2D',\n      };\n      fallbackCache.set(instanceId, newFallback);\n      return newFallback;\n    })();\n\n  const snapshot =\n    snapshotCache.get(instanceId) ??\n    (() => cameraStore.get(instanceId) ?? fallback);\n\n  snapshotCache.set(instanceId, snapshot);\n\n  return snapshot;\n}\n\n/**\n * Updates the camera state for a given map instance and notifies subscribers.\n *\n * @param instanceId - The unique identifier for the map\n * @param state - The new state to set, will be merged with existing state\n *\n * @example\n * ```tsx\n * // Update camera state manually\n * setCameraState('my-map-instance', {\n *   latitude: 37.7749,\n *   longitude: -122.4194,\n *   zoom: 10,\n *   pitch: 30,\n *   rotation: 0,\n *   projection: 'mercator',\n * });\n * ```\n */\nfunction setCameraState(\n  instanceId: UniqueId,\n  state: Partial<CameraState>,\n): void {\n  const currentState = getOrCreateState(instanceId);\n  cameraStore.set(instanceId, { ...currentState, ...state } as CameraState);\n  notifySubscribers(instanceId);\n}\n\n/**\n * Hook to access camera state actions.\n *\n * This hook uses `useSyncExternalStore` to subscribe to camera state changes,\n * providing concurrent-safe mode state updates. Uses a fan-out pattern where\n * a single bus listener per map instance notifies N React component subscribers.\n *\n * A thin wrapper around [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore).\n *\n * @param instanceId - Unique identifier for the camera to track\n * @param initialCameraState - Optional initial camera state to set\n * @param subscribe - Optional custom subscription function\n * @param getSnapshot - Optional custom snapshot getter\n * @param getServerSnapshot - Optional server-side snapshot getter\n * @returns Current camera state including latitude, longitude, zoom, pitch, rotation, projection\n *\n * @example\n * ```tsx\n * function MapInfo({ instanceId }) {\n *   const { latitude, longitude, zoom } = useCameraState({\n *     instanceId\n *   });\n *\n *   return (\n *     <div>\n *       Lat: {latitude?.toFixed(2)}, Lon: {longitude?.toFixed(2)}, Zoom: {zoom}\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With custom subscribe/getSnapshot for advanced use cases\n * function CustomMapInfo() {\n *   const customSubscribe = (onStoreChange) => {\n *     // Custom subscription logic\n *     return () => { // cleanup }\n *   }\n *\n *   const customGetSnapshot = () => {\n *     // Custom snapshot logic\n *     return { latitude: 0, longitude: 0, zoom: 1 };\n *   };\n *\n *   const viewState = useCameraState({\n *     instanceId: 'some-uuid',\n *     subscribe: customSubscribe,\n *     getSnapshot: customGetSnapshot,\n *   });\n *\n *   return <div>Custom camera state</div>;\n * }\n * ```\n */\nexport function useCameraState({\n  instanceId,\n  initialCameraState,\n  subscribe,\n  getSnapshot,\n  getServerSnapshot,\n}: UseCameraStateProps) {\n  const cameraState = useSyncExternalStore<CameraState>(\n    subscribe ?? getOrCreateSubscription(instanceId, initialCameraState),\n    getSnapshot ?? getOrCreateSnapshot(instanceId, initialCameraState),\n    getServerSnapshot,\n  );\n\n  return useMemo(\n    () => ({\n      cameraState,\n      setCameraState,\n    }),\n    [cameraState],\n  );\n}\n\n/**\n * Manually clear camera state for a specific instanceId.\n * This is typically not needed as cleanup happens automatically when all subscribers unmount.\n * Use this only in advanced scenarios where manual cleanup is required.\n *\n * @param instanceId - The unique identifier for the camera to clear\n *\n * @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearCameraState('my-map-instance');\n * ```\n */\nexport function clearCameraState(instanceId: UniqueId): void {\n  // Unsubscribe from bus if listening\n  const unsub = busUnsubscribers.get(instanceId);\n  if (unsub) {\n    unsub();\n    busUnsubscribers.delete(instanceId);\n  }\n\n  // Clear all state\n  [\n    cameraStore,\n    componentSubscribers,\n    subscriptionCache,\n    snapshotCache,\n    fallbackCache,\n  ].forEach((map) => {\n    map.delete(instanceId);\n  });\n}\n"],"mappings":"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"}

package/dist/cursor-coordinates/use-cursor-coordinates.js

@@ -16,8 +16,8 @@
 import { MapEvents } from "../deckgl/base-map/events.js";
 import { MapContext } from "../deckgl/base-map/provider.js";
 import { Broadcast } from "@accelint/bus";
-import { coordinateSystems, createCoordinate } from "@accelint/geo";
 import { useContext, useMemo, useSyncExternalStore } from "react";
+import { coordinateSystems, createCoordinate } from "@accelint/geo";
 
 //#region src/cursor-coordinates/use-cursor-coordinates.ts
 const bus = Broadcast.getInstance();

package/dist/deckgl/base-map/constants.d.ts

@@ -13,6 +13,11 @@ declare const PARAMETERS: {
   blendColorOperation: string;
   blendAlphaOperation: string;
 };
+declare const DEFAULT_VIEW_STATE: {
+  longitude: number;
+  latitude: number;
+  zoom: number;
+};
 //#endregion
-export { BASE_MAP_STYLE, PARAMETERS };
+export { BASE_MAP_STYLE, DEFAULT_VIEW_STATE, PARAMETERS };
 //# sourceMappingURL=constants.d.ts.map

package/dist/deckgl/base-map/constants.js

@@ -26,7 +26,12 @@ const PARAMETERS = {
 	blendColorOperation: "add",
 	blendAlphaOperation: "add"
 };
+const DEFAULT_VIEW_STATE = {
+	longitude: -77.0369,
+	latitude: 38.9072,
+	zoom: 4
+};
 
 //#endregion
-export { BASE_MAP_STYLE, PARAMETERS };
+export { BASE_MAP_STYLE, DEFAULT_VIEW_STATE, PARAMETERS };
 //# sourceMappingURL=constants.js.map

package/dist/deckgl/base-map/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../../../src/deckgl/base-map/constants.ts"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const BASE_MAP_STYLE =\n  'https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json';\n\nexport const PARAMETERS = {\n  depthWriteEnabled: true,\n  depthCompare: 'always',\n  depthBias: 0,\n  blend: true,\n  depthTest: false,\n  blendColorSrcFactor: 'src-alpha',\n  blendColorDstFactor: 'one-minus-src-alpha',\n  blendAlphaSrcFactor: 'one',\n  blendAlphaDstFactor: 'one-minus-src-alpha',\n  blendColorOperation: 'add',\n  blendAlphaOperation: 'add',\n};\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAa,iBACX;AAEF,MAAa,aAAa;CACxB,mBAAmB;CACnB,cAAc;CACd,WAAW;CACX,OAAO;CACP,WAAW;CACX,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACtB"}
+{"version":3,"file":"constants.js","names":[],"sources":["../../../src/deckgl/base-map/constants.ts"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const BASE_MAP_STYLE =\n  'https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json';\n\nexport const PARAMETERS = {\n  depthWriteEnabled: true,\n  depthCompare: 'always',\n  depthBias: 0,\n  blend: true,\n  depthTest: false,\n  blendColorSrcFactor: 'src-alpha',\n  blendColorDstFactor: 'one-minus-src-alpha',\n  blendAlphaSrcFactor: 'one',\n  blendAlphaDstFactor: 'one-minus-src-alpha',\n  blendColorOperation: 'add',\n  blendAlphaOperation: 'add',\n};\n\nexport const DEFAULT_VIEW_STATE = {\n  longitude: -77.0369,\n  latitude: 38.9072,\n  zoom: 4,\n};\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAa,iBACX;AAEF,MAAa,aAAa;CACxB,mBAAmB;CACnB,cAAc;CACd,WAAW;CACX,OAAO;CACP,WAAW;CACX,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACtB;AAED,MAAa,qBAAqB;CAChC,WAAW;CACX,UAAU;CACV,MAAM;CACP"}

package/dist/deckgl/base-map/controls.d.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { RefObject } from "react";
+import { UniqueId } from "@accelint/core";
+import { MapRef } from "react-map-gl/maplibre";
+
+//#region src/deckgl/base-map/controls.d.ts
+type MapControlsProps = {
+  id: UniqueId;
+  mapRef: RefObject<MapRef | null>;
+};
+/**
+ * Headless component that listens for map control events and applies them to the MapLibre instance.
+ *
+ * This component is rendered inside BaseMap to wire up event listeners
+ * for pan and zoom control events.
+ */
+declare function MapControls({
+  id,
+  mapRef
+}: MapControlsProps): null;
+//#endregion
+export { MapControls };
+//# sourceMappingURL=controls.d.ts.map

package/dist/deckgl/base-map/controls.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+'use client';
+
+import { MapEvents } from "./events.js";
+import { useOn } from "@accelint/bus/react";
+
+//#region src/deckgl/base-map/controls.tsx
+/**
+* Headless component that listens for map control events and applies them to the MapLibre instance.
+*
+* This component is rendered inside BaseMap to wire up event listeners
+* for pan and zoom control events.
+*/
+function MapControls({ id, mapRef }) {
+	useOn(MapEvents.enablePan, (event) => {
+		if (event.payload.id === id) mapRef.current?.getMap().dragPan.enable();
+	});
+	useOn(MapEvents.disablePan, (event) => {
+		if (event.payload.id === id) mapRef.current?.getMap().dragPan.disable();
+	});
+	useOn(MapEvents.enableZoom, (event) => {
+		if (event.payload.id === id) {
+			mapRef.current?.getMap().scrollZoom.enable();
+			mapRef.current?.getMap().doubleClickZoom.enable();
+		}
+	});
+	useOn(MapEvents.disableZoom, (event) => {
+		if (event.payload.id === id) {
+			mapRef.current?.getMap().scrollZoom.disable();
+			mapRef.current?.getMap().doubleClickZoom.disable();
+		}
+	});
+	return null;
+}
+
+//#endregion
+export { MapControls };
+//# sourceMappingURL=controls.js.map

package/dist/deckgl/base-map/controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controls.js","names":[],"sources":["../../../src/deckgl/base-map/controls.tsx"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n'use client';\n\nimport 'client-only';\nimport { useOn } from '@accelint/bus/react';\nimport { MapEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { RefObject } from 'react';\nimport type { MapRef } from 'react-map-gl/maplibre';\nimport type {\n  MapDisablePanEvent,\n  MapDisableZoomEvent,\n  MapEnablePanEvent,\n  MapEnableZoomEvent,\n} from './types';\n\ntype MapControlsProps = {\n  id: UniqueId;\n  mapRef: RefObject<MapRef | null>;\n};\n\n/**\n * Headless component that listens for map control events and applies them to the MapLibre instance.\n *\n * This component is rendered inside BaseMap to wire up event listeners\n * for pan and zoom control events.\n */\nexport function MapControls({ id, mapRef }: MapControlsProps) {\n  useOn<MapEnablePanEvent>(MapEvents.enablePan, (event) => {\n    if (event.payload.id === id) {\n      mapRef.current?.getMap().dragPan.enable();\n    }\n  });\n\n  useOn<MapDisablePanEvent>(MapEvents.disablePan, (event) => {\n    if (event.payload.id === id) {\n      mapRef.current?.getMap().dragPan.disable();\n    }\n  });\n\n  useOn<MapEnableZoomEvent>(MapEvents.enableZoom, (event) => {\n    if (event.payload.id === id) {\n      mapRef.current?.getMap().scrollZoom.enable();\n      mapRef.current?.getMap().doubleClickZoom.enable();\n    }\n  });\n\n  useOn<MapDisableZoomEvent>(MapEvents.disableZoom, (event) => {\n    if (event.payload.id === id) {\n      mapRef.current?.getMap().scrollZoom.disable();\n      mapRef.current?.getMap().doubleClickZoom.disable();\n    }\n  });\n\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,YAAY,EAAE,IAAI,UAA4B;AAC5D,OAAyB,UAAU,YAAY,UAAU;AACvD,MAAI,MAAM,QAAQ,OAAO,GACvB,QAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;GAE3C;AAEF,OAA0B,UAAU,aAAa,UAAU;AACzD,MAAI,MAAM,QAAQ,OAAO,GACvB,QAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;GAE5C;AAEF,OAA0B,UAAU,aAAa,UAAU;AACzD,MAAI,MAAM,QAAQ,OAAO,IAAI;AAC3B,UAAO,SAAS,QAAQ,CAAC,WAAW,QAAQ;AAC5C,UAAO,SAAS,QAAQ,CAAC,gBAAgB,QAAQ;;GAEnD;AAEF,OAA2B,UAAU,cAAc,UAAU;AAC3D,MAAI,MAAM,QAAQ,OAAO,IAAI;AAC3B,UAAO,SAAS,QAAQ,CAAC,WAAW,SAAS;AAC7C,UAAO,SAAS,QAAQ,CAAC,gBAAgB,SAAS;;GAEpD;AAEF,QAAO"}

package/dist/deckgl/base-map/events.d.ts

@@ -4,6 +4,10 @@ declare const MapEvents: {
   readonly click: "map:click";
   readonly hover: "map:hover";
   readonly viewport: "map:viewport";
+  readonly enablePan: "map:enablePan";
+  readonly disablePan: "map:disablePan";
+  readonly enableZoom: "map:enableZoom";
+  readonly disableZoom: "map:disableZoom";
 };
 //#endregion
 export { MapEvents, MapEventsNamespace };

package/dist/deckgl/base-map/events.js

@@ -16,7 +16,11 @@ const MapEventsNamespace = "map";
 const MapEvents = {
 	click: `${MapEventsNamespace}:click`,
 	hover: `${MapEventsNamespace}:hover`,
-	viewport: `${MapEventsNamespace}:viewport`
+	viewport: `${MapEventsNamespace}:viewport`,
+	enablePan: `${MapEventsNamespace}:enablePan`,
+	disablePan: `${MapEventsNamespace}:disablePan`,
+	enableZoom: `${MapEventsNamespace}:enableZoom`,
+	disableZoom: `${MapEventsNamespace}:disableZoom`
 };
 
 //#endregion

package/dist/deckgl/base-map/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const MapEventsNamespace = 'map';\n\nexport const MapEvents = {\n  click: `${MapEventsNamespace}:click`,\n  hover: `${MapEventsNamespace}:hover`,\n  viewport: `${MapEventsNamespace}:viewport`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,qBAAqB;AAElC,MAAa,YAAY;CACvB,OAAO,GAAG,mBAAmB;CAC7B,OAAO,GAAG,mBAAmB;CAC7B,UAAU,GAAG,mBAAmB;CACjC"}
+{"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const MapEventsNamespace = 'map';\n\nexport const MapEvents = {\n  click: `${MapEventsNamespace}:click`,\n  hover: `${MapEventsNamespace}:hover`,\n  viewport: `${MapEventsNamespace}:viewport`,\n  // Control events\n  enablePan: `${MapEventsNamespace}:enablePan`,\n  disablePan: `${MapEventsNamespace}:disablePan`,\n  enableZoom: `${MapEventsNamespace}:enableZoom`,\n  disableZoom: `${MapEventsNamespace}:disableZoom`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,qBAAqB;AAElC,MAAa,YAAY;CACvB,OAAO,GAAG,mBAAmB;CAC7B,OAAO,GAAG,mBAAmB;CAC7B,UAAU,GAAG,mBAAmB;CAEhC,WAAW,GAAG,mBAAmB;CACjC,YAAY,GAAG,mBAAmB;CAClC,YAAY,GAAG,mBAAmB;CAClC,aAAa,GAAG,mBAAmB;CACpC"}