npm - @accelint/map-toolkit - Versions diffs - 1.0.0 → 1.2.0 - Mend

@accelint/map-toolkit 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (84) hide show

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

@@ -13,210 +13,88 @@
 'use client';
-import { MapEvents } from "../deckgl/base-map/events.js";
 import { MapContext } from "../deckgl/base-map/provider.js";
-import { Broadcast } from "@accelint/bus";
-import { useContext, useMemo, useSyncExternalStore } from "react";
-import { coordinateSystems, createCoordinate } from "@accelint/geo";
+import { cursorCoordinateStore } from "./store.js";
+import { useContext, useMemo } from "react";
+import { getLogger } from "@accelint/logger";
+import { coordinateSystems, createCoordinate, formatDecimalDegrees, formatDegreesDecimalMinutes, formatDegreesMinutesSeconds } from "@accelint/geo";
 //#region src/cursor-coordinates/use-cursor-coordinates.ts
-const bus = Broadcast.getInstance();
-const create = createCoordinate(coordinateSystems.dd, "LONLAT");
+const logger = getLogger({
+	enabled: process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test",
+	level: "warn",
+	prefix: "[CursorCoordinates]",
+	pretty: true
+});
 const MAX_LONGITUDE = 180;
 const LONGITUDE_RANGE = 360;
-const COORDINATE_PRECISION = 8;
 const DEFAULT_COORDINATE = "--, --";
 /**
-* Prepares coordinates for display by normalizing longitude and formatting with cardinal directions.
-* Normalizes longitude to -180 to 180 range and formats both longitude and latitude with
-* compass directions (E/W for longitude, N/S for latitude).
+* Normalizes longitude to -180 to 180 range.
+* Handles wraparound including multi-revolution values.
 *
-* @param coord - Tuple of [longitude, latitude] coordinates
-* @returns Formatted string in the format "LON.NNNNNNNN E/W / LAT.NNNNNNNN N/S"
+* @param lon - Longitude value in degrees
+* @returns Normalized longitude between -180 and 180
 */
-const prepareCoord = (coord) => {
-	let lon = coord[0];
-	lon = ((lon + MAX_LONGITUDE) % LONGITUDE_RANGE + LONGITUDE_RANGE) % LONGITUDE_RANGE - MAX_LONGITUDE;
-	const lat = coord[1];
-	return `${`${Math.abs(lon).toFixed(COORDINATE_PRECISION)} ${lon < 0 ? "W" : "E"}`} / ${`${Math.abs(lat).toFixed(COORDINATE_PRECISION)} ${lat < 0 ? "S" : "N"}`}`;
-};
-/**
-* Type guard to validate that a value is a proper coordinate tuple.
-* Checks that the value is an array with exactly two finite numbers.
-*
-* @param value - Value to validate as a coordinate
-* @returns True if value is a valid [longitude, latitude] tuple
-*/
-function isValidCoordinate(value) {
-	return Array.isArray(value) && value.length === 2 && value.every(Number.isFinite);
+function normalizeLongitude(lon) {
+	return ((lon + MAX_LONGITUDE) % LONGITUDE_RANGE + LONGITUDE_RANGE) % LONGITUDE_RANGE - MAX_LONGITUDE;
 }
 /**
-* Store for cursor coordinate state keyed by instanceId
-*/
-const coordinateStore = /* @__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 map, 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 server snapshot functions per instanceId to maintain referential stability.
-* Server snapshots always return default coordinate since coordinate state is client-only.
-*/
-const serverSnapshotCache = /* @__PURE__ */ new Map();
-/**
-* 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.
+* Builds a RawCoordinate object from a coordinate tuple.
 *
-* @param instanceId - The unique identifier for the map
+* @param coord - Coordinate tuple [longitude, latitude] or null
+* @returns RawCoordinate object or null
 */
-function ensureBusListener(instanceId) {
-	if (busUnsubscribers.has(instanceId)) return;
-	const unsub = bus.on(MapEvents.hover, (data) => {
-		if (instanceId !== data.payload.id) return;
-		const coords = data.payload.info.coordinate;
-		const state = coordinateStore.get(instanceId);
-		if (state) {
-			if (isValidCoordinate(coords)) state.coordinate = coords;
-			else state.coordinate = null;
-			const subscribers = componentSubscribers.get(instanceId);
-			if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
-		}
-	});
-	busUnsubscribers.set(instanceId, unsub);
+function buildRawCoordinate(coord) {
+	if (!coord) return null;
+	return {
+		longitude: normalizeLongitude(coord[0]),
+		latitude: coord[1]
+	};
 }
 /**
-* Cleans up the bus listener if no React subscribers remain.
-*
-* @param instanceId - The unique identifier for the map
-*/
-function cleanupBusListenerIfNeeded(instanceId) {
-	const subscribers = componentSubscribers.get(instanceId);
-	if (!subscribers || subscribers.size === 0) {
-		const unsub = busUnsubscribers.get(instanceId);
-		if (unsub) {
-			unsub();
-			busUnsubscribers.delete(instanceId);
-		}
-		coordinateStore.delete(instanceId);
-		componentSubscribers.delete(instanceId);
-		subscriptionCache.delete(instanceId);
-		snapshotCache.delete(instanceId);
-		serverSnapshotCache.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 coordinate state when the last subscriber unsubscribes.
-*
-* @param instanceId - The unique identifier for the map
-* @returns A subscription function for useSyncExternalStore
-*/
-function getOrCreateSubscription(instanceId) {
-	const subscription = subscriptionCache.get(instanceId) ?? ((onStoreChange) => {
-		ensureBusListener(instanceId);
-		let subscriberSet = componentSubscribers.get(instanceId);
-		if (!subscriberSet) {
-			subscriberSet = /* @__PURE__ */ new Set();
-			componentSubscribers.set(instanceId, subscriberSet);
+* Formats a coordinate using the specified format.
+* Uses @accelint/geo formatters which match CoordinateField precision:
+* - DD: 6 decimal places
+* - DDM: 4 decimal places for minutes
+* - DMS: 2 decimal places for seconds
+*
+* @param coord - Coordinate tuple [longitude, latitude]
+* @param format - Coordinate format type
+* @returns Formatted coordinate string
+*/
+function formatCoordinate(coord, format) {
+	const normalizedLon = normalizeLongitude(coord[0]);
+	const latLon = [coord[1], normalizedLon];
+	switch (format) {
+		case "dd": return formatDecimalDegrees(latLon, {
+			withOrdinal: true,
+			separator: " / ",
+			prefix: "",
+			suffix: ""
+		});
+		case "ddm": return formatDegreesDecimalMinutes(latLon, {
+			withOrdinal: true,
+			separator: " / ",
+			prefix: "",
+			suffix: ""
+		});
+		case "dms": return formatDegreesMinutesSeconds(latLon, {
+			withOrdinal: true,
+			separator: " / ",
+			prefix: "",
+			suffix: ""
+		});
+		case "mgrs":
+		case "utm": {
+			const lat = latLon[0];
+			const lon = latLon[1];
+			const latOrdinal = lat >= 0 ? "N" : "S";
+			const lonOrdinal = lon >= 0 ? "E" : "W";
+			const formattedInput = `${Math.abs(lon).toFixed(10)} ${lonOrdinal} / ${Math.abs(lat).toFixed(10)} ${latOrdinal}`;
+			return createCoordinate(coordinateSystems.dd, "LONLAT")(formattedInput)[format]();
 		}
-		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 function must read from the store on every call to get current state.
-*
-* @param instanceId - The unique identifier for the map
-* @returns A snapshot function for useSyncExternalStore that returns formatted coordinate string
-*/
-function getOrCreateSnapshot(instanceId) {
-	let cached = snapshotCache.get(instanceId);
-	if (!cached) {
-		cached = () => {
-			const state = coordinateStore.get(instanceId);
-			if (!state) return DEFAULT_COORDINATE;
-			if (!state.coordinate) return DEFAULT_COORDINATE;
-			return create(prepareCoord(state.coordinate))[state.format]();
-		};
-		snapshotCache.set(instanceId, cached);
 	}
-	return cached;
-}
-/**
-* Creates or retrieves a cached server snapshot function for a given instanceId.
-* Server snapshots always return the default coordinate since coordinate state is client-only.
-* Required for SSR/RSC compatibility with useSyncExternalStore.
-*
-* @param instanceId - The unique identifier for the map
-* @returns A server snapshot function for useSyncExternalStore
-*/
-function getOrCreateServerSnapshot(instanceId) {
-	const serverSnapshot = serverSnapshotCache.get(instanceId) ?? (() => DEFAULT_COORDINATE);
-	serverSnapshotCache.set(instanceId, serverSnapshot);
-	return serverSnapshot;
-}
-/**
-* Updates the format for a given map instance and notifies subscribers.
-*
-* @param instanceId - The unique identifier for the map
-* @param format - The new coordinate format to use
-*/
-function setFormatForInstance(instanceId, format) {
-	const state = coordinateStore.get(instanceId);
-	if (state) {
-		state.format = format;
-		const subscribers = componentSubscribers.get(instanceId);
-		if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
-	}
-}
-/**
-* Manually clear cursor coordinate 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 map to clear
-*
-* @example
-* ```tsx
-* // Manual cleanup (rarely needed)
-* clearCursorCoordinateState('my-map-instance');
-* ```
-*/
-function clearCursorCoordinateState(instanceId) {
-	const unsub = busUnsubscribers.get(instanceId);
-	if (unsub) {
-		unsub();
-		busUnsubscribers.delete(instanceId);
-	}
-	coordinateStore.delete(instanceId);
-	componentSubscribers.delete(instanceId);
-	subscriptionCache.delete(instanceId);
-	snapshotCache.delete(instanceId);
-	serverSnapshotCache.delete(instanceId);
 }
 /**
 * React hook that tracks and formats the cursor hover position coordinates on a map.
@@ -225,17 +103,15 @@ function clearCursorCoordinateState(instanceId) {
 * geographic formats (Decimal Degrees, DMS, MGRS, UTM, etc.). The hook automatically
 * filters events to only process those from the specified map instance.
 *
-* Uses `useSyncExternalStore` for concurrent-safe updates and efficient fan-out pattern
-* where multiple components can subscribe to the same map's coordinates with a single
-* bus listener.
+* Uses the shared store factory for efficient state management and automatic cleanup.
 *
 * @param id - Optional map instance ID. If not provided, attempts to use the ID from MapProvider context.
-* @returns Object containing the formatted coordinate string and format setter function
-* @property formattedCoord - The formatted coordinate string (defaults to "--, --" when no position)
-* @property setFormat - Function to change the coordinate format system
+* @param options - Optional configuration options
+* @returns Object containing the formatted coordinate string, raw coordinate, format setter, and current format
 * @throws {Error} When no id is provided and hook is used outside MapProvider context
 *
 * @example
+* Basic usage:
 * ```tsx
 * import { uuid } from '@accelint/core';
 * import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
@@ -259,22 +135,75 @@ function clearCursorCoordinateState(instanceId) {
 *   );
 * }
 * ```
+*
+* @example
+* With custom formatter:
+* ```tsx
+* function CustomCoordinateDisplay() {
+*   const { formattedCoord, rawCoord } = useCursorCoordinates(MAP_ID, {
+*     formatter: (coord) =>
+*       `Lat: ${coord.latitude.toFixed(6)}° Lng: ${coord.longitude.toFixed(6)}°`,
+*   });
+*
+*   return <div>{formattedCoord}</div>;
+* }
+* ```
+*
+* @example
+* Accessing raw coordinates:
+* ```tsx
+* function RawCoordinateDisplay() {
+*   const { rawCoord, currentFormat } = useCursorCoordinates(MAP_ID);
+*
+*   if (!rawCoord) {
+*     return <div>Move cursor over map</div>;
+*   }
+*
+*   return (
+*     <div>
+*       <div>Longitude: {rawCoord.longitude}</div>
+*       <div>Latitude: {rawCoord.latitude}</div>
+*       <div>Format: {currentFormat}</div>
+*     </div>
+*   );
+* }
+* ```
 */
-function useCursorCoordinates(id) {
+function useCursorCoordinates(id, options) {
 	const contextId = useContext(MapContext);
 	const actualId = id ?? contextId;
 	if (!actualId) throw new Error("useCursorCoordinates requires either an id parameter or to be used within a MapProvider");
-	if (!coordinateStore.has(actualId)) coordinateStore.set(actualId, {
-		coordinate: null,
-		format: "dd"
-	});
-	const formattedCoord = useSyncExternalStore(getOrCreateSubscription(actualId), getOrCreateSnapshot(actualId), getOrCreateServerSnapshot(actualId));
+	const customFormatter = options?.formatter;
+	const { state, setFormat } = cursorCoordinateStore.use(actualId);
+	const rawCoord = useMemo(() => buildRawCoordinate(state.coordinate), [state.coordinate]);
+	const formattedCoord = useMemo(() => {
+		if (!rawCoord) return DEFAULT_COORDINATE;
+		if (customFormatter) try {
+			return customFormatter(rawCoord);
+		} catch (error) {
+			logger.error(`Custom formatter failed: ${error instanceof Error ? error.message : String(error)}`);
+			return DEFAULT_COORDINATE;
+		}
+		return formatCoordinate(state.coordinate, state.format);
+	}, [
+		rawCoord,
+		customFormatter,
+		state.format,
+		state.coordinate
+	]);
 	return useMemo(() => ({
 		formattedCoord,
-		setFormat: (format) => setFormatForInstance(actualId, format)
-	}), [formattedCoord, actualId]);
+		setFormat,
+		rawCoord,
+		currentFormat: state.format
+	}), [
+		formattedCoord,
+		setFormat,
+		rawCoord,
+		state.format
+	]);
 }
 //#endregion
-export { clearCursorCoordinateState, useCursorCoordinates };
+export { useCursorCoordinates };
 //# sourceMappingURL=use-cursor-coordinates.js.map

package/dist/cursor-coordinates/use-cursor-coordinates.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"use-cursor-coordinates.js","names":[],"sources":["../../src/cursor-coordinates/use-cursor-coordinates.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'use client';\n\nimport 'client-only';\nimport { Broadcast } from '@accelint/bus';\nimport { coordinateSystems, createCoordinate } from '@accelint/geo';\nimport { useContext, useMemo, useSyncExternalStore } from 'react';\nimport { MapEvents } from '../deckgl/base-map/events';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport type { UniqueId } from '@accelint/core';\nimport type { MapEventType, MapHoverEvent } from '../deckgl/base-map/types';\n\n/\n Supported coordinate format types for displaying map coordinates.\n \n @typedef {'dd' \| 'ddm' \| 'dms' \| 'mgrs' \| 'utm'} CoordinateFormatTypes\n * @property dd - Decimal Degrees (e.g., \"45.50000000 E / 30.25000000 N\")\n * @property ddm - Degrees Decimal Minutes (e.g., \"45° 30' E / 30° 15' N\")\n * @property dms - Degrees Minutes Seconds (e.g., \"45° 30' 0\\\" E / 30° 15' 0\\\" N\")\n * @property mgrs - Military Grid Reference System (e.g., \"31U DQ 48251 11932\")\n * @property utm - Universal Transverse Mercator (e.g., \"31N 448251 5411932\")\n /\nexport type CoordinateFormatTypes = keyof typeof coordinateSystems;\n\nconst bus = Broadcast.getInstance<MapEventType>();\nconst create = createCoordinate(coordinateSystems.dd, 'LONLAT');\n\nconst MAX_LONGITUDE = 180;\nconst LONGITUDE_RANGE = 360;\nconst COORDINATE_PRECISION = 8;\nconst DEFAULT_COORDINATE = '--, --';\n\n/\n Prepares coordinates for display by normalizing longitude and formatting with cardinal directions.\n * Normalizes longitude to -180 to 180 range and formats both longitude and latitude with\n * compass directions (E/W for longitude, N/S for latitude).\n \n @param coord - Tuple of [longitude, latitude] coordinates\n * @returns Formatted string in the format \"LON.NNNNNNNN E/W / LAT.NNNNNNNN N/S\"\n /\nconst prepareCoord = (coord: [number, number]) => {\n // Normalize longitude to -180 to 180 range (handles wraparound including multi-revolution values)\n let lon = coord[0];\n lon =\n ((((lon + MAX_LONGITUDE) % LONGITUDE_RANGE) + LONGITUDE_RANGE) %\n LONGITUDE_RANGE) -\n MAX_LONGITUDE;\n\n const lat = coord[1];\n const lonStr = `${Math.abs(lon).toFixed(COORDINATE_PRECISION)} ${lon < 0 ? 'W' : 'E'}`;\n const latStr = `${Math.abs(lat).toFixed(COORDINATE_PRECISION)} ${lat < 0 ? 'S' : 'N'}`;\n\n return `${lonStr} / ${latStr}`;\n};\n\n/\n Type guard to validate that a value is a proper coordinate tuple.\n * Checks that the value is an array with exactly two finite numbers.\n \n @param value - Value to validate as a coordinate\n * @returns True if value is a valid [longitude, latitude] tuple\n /\nfunction isValidCoordinate(value?: number[]): value is [number, number] {\n return (\n Array.isArray(value) && value.length === 2 && value.every(Number.isFinite)\n );\n}\n\n/\n State stored for each map instance's cursor coordinates\n /\ntype CursorCoordinateState = {\n coordinate: [number, number] \| null;\n format: CoordinateFormatTypes;\n};\n\n/\n Store for cursor coordinate state keyed by instanceId\n /\nconst coordinateStore = new Map<UniqueId, CursorCoordinateState>();\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 map, 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, () => string>();\n\n/\n Cache of server snapshot functions per instanceId to maintain referential stability.\n * Server snapshots always return default coordinate since coordinate state is client-only.\n /\nconst serverSnapshotCache = new Map<UniqueId, () => string>();\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 map\n /\nfunction ensureBusListener(instanceId: UniqueId): void {\n if (busUnsubscribers.has(instanceId)) {\n return; // Already listening\n }\n\n const unsub = bus.on(MapEvents.hover, (data: MapHoverEvent) => {\n const eventId = data.payload.id;\n\n // Ignore hover events from other possible map instances\n if (instanceId !== eventId) {\n return;\n }\n\n const coords = data.payload.info.coordinate;\n const state = coordinateStore.get(instanceId);\n\n // Update coordinate if valid, or clear if invalid\n if (state) {\n if (isValidCoordinate(coords)) {\n state.coordinate = coords as [number, number];\n } else {\n state.coordinate = null;\n }\n\n // Fan-out: notify all React subscribers\n const subscribers = componentSubscribers.get(instanceId);\n if (subscribers) {\n for (const onStoreChange of subscribers) {\n onStoreChange();\n }\n }\n }\n });\n\n busUnsubscribers.set(instanceId, unsub);\n}\n\n/\n Cleans up the bus listener if no React subscribers remain.\n \n @param instanceId - The unique identifier for the map\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 coordinateStore.delete(instanceId);\n componentSubscribers.delete(instanceId);\n subscriptionCache.delete(instanceId);\n snapshotCache.delete(instanceId);\n serverSnapshotCache.delete(instanceId);\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 coordinate state when the last subscriber unsubscribes.\n \n @param instanceId - The unique identifier for the map\n * @returns A subscription function for useSyncExternalStore\n /\nfunction getOrCreateSubscription(\n instanceId: UniqueId,\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);\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 function must read from the store on every call to get current state.\n \n @param instanceId - The unique identifier for the map\n * @returns A snapshot function for useSyncExternalStore that returns formatted coordinate string\n /\nfunction getOrCreateSnapshot(instanceId: UniqueId): () => string {\n let cached = snapshotCache.get(instanceId);\n\n if (!cached) {\n // Create a snapshot function that always reads current state from the store\n cached = () => {\n const state = coordinateStore.get(instanceId);\n\n if (!state) {\n return DEFAULT_COORDINATE;\n }\n\n if (!state.coordinate) {\n return DEFAULT_COORDINATE;\n }\n\n const coord = create(prepareCoord(state.coordinate));\n return coord[state.format]();\n };\n\n snapshotCache.set(instanceId, cached);\n }\n\n return cached;\n}\n\n/\n Creates or retrieves a cached server snapshot function for a given instanceId.\n * Server snapshots always return the default coordinate since coordinate state is client-only.\n * Required for SSR/RSC compatibility with useSyncExternalStore.\n \n @param instanceId - The unique identifier for the map\n * @returns A server snapshot function for useSyncExternalStore\n /\nfunction getOrCreateServerSnapshot(instanceId: UniqueId): () => string {\n const serverSnapshot =\n serverSnapshotCache.get(instanceId) ?? (() => DEFAULT_COORDINATE);\n\n serverSnapshotCache.set(instanceId, serverSnapshot);\n\n return serverSnapshot;\n}\n\n/\n Updates the format for a given map instance and notifies subscribers.\n \n @param instanceId - The unique identifier for the map\n * @param format - The new coordinate format to use\n /\nfunction setFormatForInstance(\n instanceId: UniqueId,\n format: CoordinateFormatTypes,\n): void {\n const state = coordinateStore.get(instanceId);\n if (state) {\n state.format = format;\n\n // Notify all subscribers of the format change\n // The coordinate remains unchanged; only the display format changes\n const subscribers = componentSubscribers.get(instanceId);\n if (subscribers) {\n for (const onStoreChange of subscribers) {\n onStoreChange();\n }\n }\n }\n}\n\n/\n Manually clear cursor coordinate 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 map to clear\n \n @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearCursorCoordinateState('my-map-instance');\n * ```\n /\nexport function clearCursorCoordinateState(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 coordinateStore.delete(instanceId);\n componentSubscribers.delete(instanceId);\n subscriptionCache.delete(instanceId);\n snapshotCache.delete(instanceId);\n serverSnapshotCache.delete(instanceId);\n}\n\n/\n React hook that tracks and formats the cursor hover position coordinates on a map.\n \n Subscribes to map hover events via the event bus and converts coordinates to various\n * geographic formats (Decimal Degrees, DMS, MGRS, UTM, etc.). The hook automatically\n * filters events to only process those from the specified map instance.\n \n Uses `useSyncExternalStore` for concurrent-safe updates and efficient fan-out pattern\n * where multiple components can subscribe to the same map's coordinates with a single\n * bus listener.\n \n @param id - Optional map instance ID. If not provided, attempts to use the ID from MapProvider context.\n * @returns Object containing the formatted coordinate string and format setter function\n * @property formattedCoord - The formatted coordinate string (defaults to \"--, --\" when no position)\n * @property setFormat - Function to change the coordinate format system\n * @throws {Error} When no id is provided and hook is used outside MapProvider context\n \n @example\n * ```tsx\n * import { uuid } from '@accelint/core';\n * import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';\n \n const MAP_ID = uuid();\n \n function CoordinateDisplay() {\n * const { formattedCoord, setFormat } = useCursorCoordinates(MAP_ID);\n \n return (\n * <div>\n * <select onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}>\n * <option value=\"dd\">Decimal Degrees</option>\n * <option value=\"ddm\">Degrees Decimal Minutes</option>\n * <option value=\"dms\">Degrees Minutes Seconds</option>\n * <option value=\"mgrs\">MGRS</option>\n * <option value=\"utm\">UTM</option>\n * </select>\n * <div>{formattedCoord}</div>\n * </div>\n * );\n * }\n * ```\n */\nexport function useCursorCoordinates(id?: UniqueId) {\n const contextId = useContext(MapContext);\n const actualId = id ?? contextId;\n\n if (!actualId) {\n throw new Error(\n 'useCursorCoordinates requires either an id parameter or to be used within a MapProvider',\n );\n }\n\n // Initialize state for this map instance BEFORE subscribing\n // This ensures the bus listener has a store to write to\n if (!coordinateStore.has(actualId)) {\n coordinateStore.set(actualId, {\n coordinate: null,\n format: 'dd',\n });\n }\n\n // Subscribe to coordinate changes using useSyncExternalStore\n // This must happen after store initialization\n // Third parameter provides server snapshot for SSR/RSC compatibility\n const formattedCoord = useSyncExternalStore<string>(\n getOrCreateSubscription(actualId),\n getOrCreateSnapshot(actualId),\n getOrCreateServerSnapshot(actualId),\n );\n\n // Memoize the return value to prevent unnecessary re-renders\n return useMemo(\n () => ({\n formattedCoord,\n setFormat: (format: CoordinateFormatTypes) =>\n setFormatForInstance(actualId, format),\n }),\n [formattedCoord, actualId],\n );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAM,MAAM,UAAU,aAA2B;AACjD,MAAM,SAAS,iBAAiB,kBAAkB,IAAI,SAAS;AAE/D,MAAM,gBAAgB;AACtB,MAAM,kBAAkB;AACxB,MAAM,uBAAuB;AAC7B,MAAM,qBAAqB;;;;;;;;;AAU3B,MAAM,gBAAgB,UAA4B;CAEhD,IAAI,MAAM,MAAM;AAChB,SACM,MAAM,iBAAiB,kBAAmB,mBAC5C,kBACF;CAEF,MAAM,MAAM,MAAM;AAIlB,QAAO,GAHQ,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,qBAAqB,CAAC,GAAG,MAAM,IAAI,MAAM,MAGhE,KAFF,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,qBAAqB,CAAC,GAAG,MAAM,IAAI,MAAM;;;;;;;;;AAYnF,SAAS,kBAAkB,OAA6C;AACtE,QACE,MAAM,QAAQ,MAAM,IAAI,MAAM,WAAW,KAAK,MAAM,MAAM,OAAO,SAAS;;;;;AAe9E,MAAM,kCAAkB,IAAI,KAAsC;;;;;AAMlE,MAAM,uCAAuB,IAAI,KAAgC;;;;;;AAOjE,MAAM,mCAAmB,IAAI,KAA2B;;;;AAMxD,MAAM,oCAAoB,IAAI,KAA6B;;;;AAK3D,MAAM,gCAAgB,IAAI,KAA6B;;;;;AAMvD,MAAM,sCAAsB,IAAI,KAA6B;;;;;;;;AAS7D,SAAS,kBAAkB,YAA4B;AACrD,KAAI,iBAAiB,IAAI,WAAW,CAClC;CAGF,MAAM,QAAQ,IAAI,GAAG,UAAU,QAAQ,SAAwB;AAI7D,MAAI,eAHY,KAAK,QAAQ,GAI3B;EAGF,MAAM,SAAS,KAAK,QAAQ,KAAK;EACjC,MAAM,QAAQ,gBAAgB,IAAI,WAAW;AAG7C,MAAI,OAAO;AACT,OAAI,kBAAkB,OAAO,CAC3B,OAAM,aAAa;OAEnB,OAAM,aAAa;GAIrB,MAAM,cAAc,qBAAqB,IAAI,WAAW;AACxD,OAAI,YACF,MAAK,MAAM,iBAAiB,YAC1B,gBAAe;;GAIrB;AAEF,kBAAiB,IAAI,YAAY,MAAM;;;;;;;AAQzC,SAAS,2BAA2B,YAA4B;CAC9D,MAAM,cAAc,qBAAqB,IAAI,WAAW;AAExD,KAAI,CAAC,eAAe,YAAY,SAAS,GAAG;EAE1C,MAAM,QAAQ,iBAAiB,IAAI,WAAW;AAC9C,MAAI,OAAO;AACT,UAAO;AACP,oBAAiB,OAAO,WAAW;;AAIrC,kBAAgB,OAAO,WAAW;AAClC,uBAAqB,OAAO,WAAW;AACvC,oBAAkB,OAAO,WAAW;AACpC,gBAAc,OAAO,WAAW;AAChC,sBAAoB,OAAO,WAAW;;;;;;;;;;;AAY1C,SAAS,wBACP,YAC2C;CAC3C,MAAM,eACJ,kBAAkB,IAAI,WAAW,MAC/B,kBAA8B;AAE9B,oBAAkB,WAAW;EAG7B,IAAI,gBAAgB,qBAAqB,IAAI,WAAW;AACxD,MAAI,CAAC,eAAe;AAClB,mCAAgB,IAAI,KAAK;AACzB,wBAAqB,IAAI,YAAY,cAAc;;AAErD,gBAAc,IAAI,cAAc;AAGhC,eAAa;GACX,MAAM,uBAAuB,qBAAqB,IAAI,WAAW;AACjE,OAAI,qBACF,sBAAqB,OAAO,cAAc;AAI5C,8BAA2B,WAAW;;;AAI5C,mBAAkB,IAAI,YAAY,aAAa;AAE/C,QAAO;;;;;;;;;AAUT,SAAS,oBAAoB,YAAoC;CAC/D,IAAI,SAAS,cAAc,IAAI,WAAW;AAE1C,KAAI,CAAC,QAAQ;AAEX,iBAAe;GACb,MAAM,QAAQ,gBAAgB,IAAI,WAAW;AAE7C,OAAI,CAAC,MACH,QAAO;AAGT,OAAI,CAAC,MAAM,WACT,QAAO;AAIT,UADc,OAAO,aAAa,MAAM,WAAW,CAAC,CACvC,MAAM,SAAS;;AAG9B,gBAAc,IAAI,YAAY,OAAO;;AAGvC,QAAO;;;;;;;;;;AAWT,SAAS,0BAA0B,YAAoC;CACrE,MAAM,iBACJ,oBAAoB,IAAI,WAAW,WAAW;AAEhD,qBAAoB,IAAI,YAAY,eAAe;AAEnD,QAAO;;;;;;;;AAST,SAAS,qBACP,YACA,QACM;CACN,MAAM,QAAQ,gBAAgB,IAAI,WAAW;AAC7C,KAAI,OAAO;AACT,QAAM,SAAS;EAIf,MAAM,cAAc,qBAAqB,IAAI,WAAW;AACxD,MAAI,YACF,MAAK,MAAM,iBAAiB,YAC1B,gBAAe;;;;;;;;;;;;;;;;AAmBvB,SAAgB,2BAA2B,YAA4B;CAErE,MAAM,QAAQ,iBAAiB,IAAI,WAAW;AAC9C,KAAI,OAAO;AACT,SAAO;AACP,mBAAiB,OAAO,WAAW;;AAIrC,iBAAgB,OAAO,WAAW;AAClC,sBAAqB,OAAO,WAAW;AACvC,mBAAkB,OAAO,WAAW;AACpC,eAAc,OAAO,WAAW;AAChC,qBAAoB,OAAO,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CxC,SAAgB,qBAAqB,IAAe;CAClD,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,0FACD;AAKH,KAAI,CAAC,gBAAgB,IAAI,SAAS,CAChC,iBAAgB,IAAI,UAAU;EAC5B,YAAY;EACZ,QAAQ;EACT,CAAC;CAMJ,MAAM,iBAAiB,qBACrB,wBAAwB,SAAS,EACjC,oBAAoB,SAAS,EAC7B,0BAA0B,SAAS,CACpC;AAGD,QAAO,eACE;EACL;EACA,YAAY,WACV,qBAAqB,UAAU,OAAO;EACzC,GACD,CAAC,gBAAgB,SAAS,CAC3B"}
1	+ {"version":3,"file":"use-cursor-coordinates.js","names":["latLon: [number, number]"],"sources":["../../src/cursor-coordinates/use-cursor-coordinates.ts"],"sourcesContent":["/\n Copyright 2026 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'use client';\n\nimport 'client-only';\nimport {\n coordinateSystems,\n createCoordinate,\n formatDecimalDegrees,\n formatDegreesDecimalMinutes,\n formatDegreesMinutesSeconds,\n} from '@accelint/geo';\nimport { getLogger } from '@accelint/logger';\nimport { useContext, useMemo } from 'react';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport { cursorCoordinateStore } from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type {\n CoordinateFormatTypes,\n RawCoordinate,\n UseCursorCoordinatesOptions,\n UseCursorCoordinatesReturn,\n} from './types';\n\nconst logger = getLogger({\n enabled:\n process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n level: 'warn',\n prefix: '[CursorCoordinates]',\n pretty: true,\n});\n\nconst MAX_LONGITUDE = 180;\nconst LONGITUDE_RANGE = 360;\nconst DEFAULT_COORDINATE = '--, --';\n\n/\n Normalizes longitude to -180 to 180 range.\n * Handles wraparound including multi-revolution values.\n \n @param lon - Longitude value in degrees\n * @returns Normalized longitude between -180 and 180\n /\nfunction normalizeLongitude(lon: number): number {\n return (\n ((((lon + MAX_LONGITUDE) % LONGITUDE_RANGE) + LONGITUDE_RANGE) %\n LONGITUDE_RANGE) -\n MAX_LONGITUDE\n );\n}\n\n/\n Builds a RawCoordinate object from a coordinate tuple.\n \n @param coord - Coordinate tuple [longitude, latitude] or null\n * @returns RawCoordinate object or null\n /\nfunction buildRawCoordinate(coord: [number, number] \| null): RawCoordinate {\n if (!coord) {\n return null;\n }\n\n const normalizedLon = normalizeLongitude(coord[0]);\n\n return {\n longitude: normalizedLon,\n latitude: coord[1],\n };\n}\n\n/\n Formats a coordinate using the specified format.\n * Uses @accelint/geo formatters which match CoordinateField precision:\n * - DD: 6 decimal places\n * - DDM: 4 decimal places for minutes\n * - DMS: 2 decimal places for seconds\n \n @param coord - Coordinate tuple [longitude, latitude]\n * @param format - Coordinate format type\n * @returns Formatted coordinate string\n /\nfunction formatCoordinate(\n coord: [number, number],\n format: CoordinateFormatTypes,\n): string {\n // Normalize longitude and convert to [lat, lon] for geo formatters\n const normalizedLon = normalizeLongitude(coord[0]);\n const latLon: [number, number] = [coord[1], normalizedLon];\n\n switch (format) {\n case 'dd':\n return formatDecimalDegrees(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'ddm':\n return formatDegreesDecimalMinutes(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'dms':\n return formatDegreesMinutesSeconds(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'mgrs':\n case 'utm': {\n // Use createCoordinate for grid-based formats\n // Input format: \"lon E / lat N\" for LONLAT (matching geo package DD tests)\n // Limit to 10 decimal places (geo parser max) and avoid floating point precision issues\n const lat = latLon[0];\n const lon = latLon[1];\n const latOrdinal = lat >= 0 ? 'N' : 'S';\n const lonOrdinal = lon >= 0 ? 'E' : 'W';\n // Use LONLAT format: longitude first, then latitude\n // toFixed(10) ensures we stay within the parser's regex limits\n const formattedInput = `${Math.abs(lon).toFixed(10)} ${lonOrdinal} / ${Math.abs(lat).toFixed(10)} ${latOrdinal}`;\n\n const geoCoord = createCoordinate(\n coordinateSystems.dd,\n 'LONLAT',\n )(formattedInput);\n\n return geoCoord[format]();\n }\n }\n}\n\n/\n React hook that tracks and formats the cursor hover position coordinates on a map.\n \n Subscribes to map hover events via the event bus and converts coordinates to various\n * geographic formats (Decimal Degrees, DMS, MGRS, UTM, etc.). The hook automatically\n * filters events to only process those from the specified map instance.\n \n Uses the shared store factory for efficient state management and automatic cleanup.\n \n @param id - Optional map instance ID. If not provided, attempts to use the ID from MapProvider context.\n * @param options - Optional configuration options\n * @returns Object containing the formatted coordinate string, raw coordinate, format setter, and current format\n * @throws {Error} When no id is provided and hook is used outside MapProvider context\n \n @example\n * Basic usage:\n * ```tsx\n * import { uuid } from '@accelint/core';\n * import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';\n \n const MAP_ID = uuid();\n \n function CoordinateDisplay() {\n * const { formattedCoord, setFormat } = useCursorCoordinates(MAP_ID);\n \n return (\n * <div>\n * <select onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}>\n * <option value=\"dd\">Decimal Degrees</option>\n * <option value=\"ddm\">Degrees Decimal Minutes</option>\n * <option value=\"dms\">Degrees Minutes Seconds</option>\n * <option value=\"mgrs\">MGRS</option>\n * <option value=\"utm\">UTM</option>\n * </select>\n * <div>{formattedCoord}</div>\n * </div>\n * );\n * }\n * ```\n \n @example\n * With custom formatter:\n * ```tsx\n * function CustomCoordinateDisplay() {\n * const { formattedCoord, rawCoord } = useCursorCoordinates(MAP_ID, {\n * formatter: (coord) =>\n * `Lat: ${coord.latitude.toFixed(6)}° Lng: ${coord.longitude.toFixed(6)}°`,\n * });\n \n return <div>{formattedCoord}</div>;\n * }\n * ```\n \n @example\n * Accessing raw coordinates:\n * ```tsx\n * function RawCoordinateDisplay() {\n * const { rawCoord, currentFormat } = useCursorCoordinates(MAP_ID);\n \n if (!rawCoord) {\n * return <div>Move cursor over map</div>;\n * }\n \n return (\n * <div>\n * <div>Longitude: {rawCoord.longitude}</div>\n * <div>Latitude: {rawCoord.latitude}</div>\n * <div>Format: {currentFormat}</div>\n * </div>\n * );\n * }\n * ```\n */\nexport function useCursorCoordinates(\n id?: UniqueId,\n options?: UseCursorCoordinatesOptions,\n): UseCursorCoordinatesReturn {\n const contextId = useContext(MapContext);\n const actualId = id ?? contextId;\n\n if (!actualId) {\n throw new Error(\n 'useCursorCoordinates requires either an id parameter or to be used within a MapProvider',\n );\n }\n\n const customFormatter = options?.formatter;\n\n // Use the store hook to get state and actions\n const { state, setFormat } = cursorCoordinateStore.use(actualId);\n\n // Build raw coordinate object\n const rawCoord = useMemo(\n () => buildRawCoordinate(state.coordinate),\n [state.coordinate],\n );\n\n // Compute formatted coordinate string\n const formattedCoord = useMemo(() => {\n if (!rawCoord) {\n return DEFAULT_COORDINATE;\n }\n\n // Use custom formatter if provided\n if (customFormatter) {\n try {\n return customFormatter(rawCoord);\n } catch (error) {\n logger.error(\n `Custom formatter failed: ${error instanceof Error ? error.message : String(error)}`,\n );\n return DEFAULT_COORDINATE;\n }\n }\n\n // Use built-in formatter\n return formatCoordinate(state.coordinate!, state.format);\n }, [rawCoord, customFormatter, state.format, state.coordinate]);\n\n // Memoize the return value to prevent unnecessary re-renders\n return useMemo(\n () => ({\n formattedCoord,\n setFormat,\n rawCoord,\n currentFormat: state.format,\n }),\n [formattedCoord, setFormat, rawCoord, state.format],\n );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAiCA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;AAEF,MAAM,gBAAgB;AACtB,MAAM,kBAAkB;AACxB,MAAM,qBAAqB;;;;;;;;AAS3B,SAAS,mBAAmB,KAAqB;AAC/C,UACM,MAAM,iBAAiB,kBAAmB,mBAC5C,kBACF;;;;;;;;AAUJ,SAAS,mBAAmB,OAA+C;AACzE,KAAI,CAAC,MACH,QAAO;AAKT,QAAO;EACL,WAHoB,mBAAmB,MAAM,GAAG;EAIhD,UAAU,MAAM;EACjB;;;;;;;;;;;;;AAcH,SAAS,iBACP,OACA,QACQ;CAER,MAAM,gBAAgB,mBAAmB,MAAM,GAAG;CAClD,MAAMA,SAA2B,CAAC,MAAM,IAAI,cAAc;AAE1D,SAAQ,QAAR;EACE,KAAK,KACH,QAAO,qBAAqB,QAAQ;GAClC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK,MACH,QAAO,4BAA4B,QAAQ;GACzC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK,MACH,QAAO,4BAA4B,QAAQ;GACzC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK;EACL,KAAK,OAAO;GAIV,MAAM,MAAM,OAAO;GACnB,MAAM,MAAM,OAAO;GACnB,MAAM,aAAa,OAAO,IAAI,MAAM;GACpC,MAAM,aAAa,OAAO,IAAI,MAAM;GAGpC,MAAM,iBAAiB,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,WAAW,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG;AAOpG,UALiB,iBACf,kBAAkB,IAClB,SACD,CAAC,eAAe,CAED,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8E/B,SAAgB,qBACd,IACA,SAC4B;CAC5B,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,0FACD;CAGH,MAAM,kBAAkB,SAAS;CAGjC,MAAM,EAAE,OAAO,cAAc,sBAAsB,IAAI,SAAS;CAGhE,MAAM,WAAW,cACT,mBAAmB,MAAM,WAAW,EAC1C,CAAC,MAAM,WAAW,CACnB;CAGD,MAAM,iBAAiB,cAAc;AACnC,MAAI,CAAC,SACH,QAAO;AAIT,MAAI,gBACF,KAAI;AACF,UAAO,gBAAgB,SAAS;WACzB,OAAO;AACd,UAAO,MACL,4BAA4B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GACnF;AACD,UAAO;;AAKX,SAAO,iBAAiB,MAAM,YAAa,MAAM,OAAO;IACvD;EAAC;EAAU;EAAiB,MAAM;EAAQ,MAAM;EAAW,CAAC;AAG/D,QAAO,eACE;EACL;EACA;EACA;EACA,eAAe,MAAM;EACtB,GACD;EAAC;EAAgB;EAAW;EAAU,MAAM;EAAO,CACpD"}

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

@@ -11,8 +11,8 @@
  */
 import { RefObject } from "react";
-import { UniqueId } from "@accelint/core";
 import { MapRef } from "react-map-gl/maplibre";
+import { UniqueId } from "@accelint/core";
 //#region src/deckgl/base-map/controls.d.ts
 type MapControlsProps = {

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

	@@ -1 +1 @@
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 mapRef.current?.getMap().boxZoom.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 mapRef.current?.getMap().boxZoom.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;AACjD,UAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;;GAE3C;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;AAClD,UAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;;GAE5C;AAEF,QAAO"}
1	+ {"version":3,"file":"controls.js","names":[],"sources":["../../../src/deckgl/base-map/controls.tsx"],"sourcesContent":["/\n Copyright 2026 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 mapRef.current?.getMap().boxZoom.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 mapRef.current?.getMap().boxZoom.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;AACjD,UAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;;GAE3C;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;AAClD,UAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;;GAE5C;AAEF,QAAO"}

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

	@@ -1 +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 // 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"}
1	+ {"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"sourcesContent":["/\n Copyright 2026 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"}

package/dist/deckgl/base-map/index.d.ts CHANGED Viewed

@@ -11,7 +11,7 @@
  */
 import { BaseMapProps } from "./types.js";
-import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 //#region src/deckgl/base-map/index.d.ts
@@ -106,7 +106,7 @@ declare function BaseMap({
   onViewStateChange,
   pickingRadius,
   ...rest
-}: BaseMapProps): react_jsx_runtime1.JSX.Element;
+}: BaseMapProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { BaseMap };
 //# sourceMappingURL=index.d.ts.map

package/dist/deckgl/base-map/index.js CHANGED Viewed

@@ -14,17 +14,17 @@
 'use client';
 import { useMapCamera } from "../../camera/store.js";
-import { MapEvents } from "./events.js";
 import { getCursor } from "../../map-cursor/store.js";
-import { MapProvider } from "./provider.js";
 import { DEFAULT_VIEW_STATE } from "../../shared/constants.js";
 import { DARK_BASE_MAP_STYLE, PARAMETERS, PICKING_RADIUS } from "./constants.js";
+import { MapEvents } from "./events.js";
 import { MapControls } from "./controls.js";
+import { MapProvider } from "./provider.js";
 import { useCallback, useId, useMemo, useRef } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffectEvent, useEmit } from "@accelint/bus/react";
 import { Deckgl, useDeckgl } from "@deckgl-fiber-renderer/dom";
 import { Map, useControl } from "react-map-gl/maplibre";
+import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/deckgl/base-map/index.tsx
 /**

package/dist/deckgl/base-map/provider.d.ts CHANGED Viewed

@@ -12,7 +12,7 @@
 import { ReactNode } from "react";
 import { UniqueId } from "@accelint/core";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
 //#region src/deckgl/base-map/provider.d.ts
 /**
@@ -139,7 +139,7 @@ type MapProviderProps = {
 declare function MapProvider({
   children,
   id
-}: MapProviderProps): react_jsx_runtime0.JSX.Element;
+}: MapProviderProps): react_jsx_runtime1.JSX.Element;
 //#endregion
 export { MapContext, MapProvider, MapProviderProps };
 //# sourceMappingURL=provider.d.ts.map

package/dist/deckgl/base-map/provider.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"provider.js","names":[],"sources":["../../../src/deckgl/base-map/provider.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 { createContext, type ReactNode, useEffect } from 'react';\nimport { clearCursorState } from '../../map-cursor/store';\nimport { clearMapModeState } from '../../map-mode/store';\nimport type { UniqueId } from '@accelint/core';\n\n/\n React context for map ID.\n * Use the `useMapMode` hook to access the map mode state.\n /\nexport const MapContext = createContext<UniqueId \| null>(null);\n\n/\n Props for the MapProvider component.\n /\nexport type MapProviderProps = {\n /* Child components that will have access to map mode context /\n children: ReactNode;\n /\n Unique identifier for this map instance.\n \n Used to isolate mode changes between different map instances (e.g., main map vs minimap).\n * This is required and should be provided by the parent component (typically BaseMap).\n \n @example\n * ```tsx\n * // Multiple independent map instances\n * const mainMapId = uuid();\n * const minimapId = uuid();\n \n <MapProvider id={mainMapId}>\n * // Map layers and components\n * </MapProvider>\n \n <MapProvider id={minimapId}>\n * // Minimap layers and components\n * </MapProvider>\n * ```\n /\n id: UniqueId;\n};\n\n/\n Provider component for managing map modes with ownership and authorization.\n \n Note: This provider is used internally by `BaseMap` and should not be used directly.\n * Consumers should pass the `id` prop to `BaseMap`, which will create this provider automatically.\n \n This component uses a hybrid architecture combining React Context (for map instance identity)\n * with module-level state management (for map mode state). The provider:\n * - Provides a unique `id` via Context\n * - Cleans up map mode state when unmounted\n * - Allows components to subscribe to mode changes via `useMapMode` hook (which uses `useSyncExternalStore`)\n \n The module-level state management system implements a state machine for map modes where\n * components can request mode changes with ownership. When a mode is owned by a component,\n * other components must request authorization to change to a different mode. The system handles:\n \n - Automatic mode changes when no ownership conflicts exist\n * - Authorization flow when switching between owned modes\n * - Per-mode ownership tracking that persists throughout the session\n * - Pending request management (one pending request per requester)\n * - Auto-acceptance of first pending request when mode owner returns to default\n * - Auto-rejection of other pending requests when one is approved\n * - Event emission through a centralized event bus\n * - Instance isolation for multiple map scenarios (main map + minimap)\n * - Always initializes in 'default' mode\n \n ## Instance Isolation\n \n Each MapProvider instance operates independently. Mode changes in one instance\n * do not affect other instances, even when multiple maps are rendered on the same page.\n * This enables scenarios like:\n * - Main map in \"drawing\" mode while minimap stays in \"view\" mode\n * - Multiple independent map views with different interaction modes\n \n Events are scoped to specific instances using the `id` prop. The event bus\n * filters events to ensure each provider only responds to events for its own instance.\n \n ## Pending Request Behavior\n \n - Pending requests are stored by requester ID (not mode owner)\n * - Each requester can have only one pending request at a time\n * - New requests from the same requester auto-replace previous requests\n * - Pending requests persist when mode owner switches between their own modes\n * - When any request is approved, all other pending requests are auto-rejected\n * - When mode owner returns to default mode:\n * - If first pending request is for default mode, all pending requests are rejected (already in requested mode)\n * - If first pending request is for a different mode, that request is auto-approved and others are rejected\n \n ## Instance ID Stability and Lifecycle\n \n The provider's cleanup mechanism (via `useEffect`) ensures proper state management:\n * - Map mode state is cleaned up when the provider unmounts\n * - Changing the `id` prop will trigger cleanup of the old state via the effect dependency\n * - State is lazily initialized on first subscription (no manual creation needed)\n \n While the `id` prop should typically remain stable (created as a module-level constant\n * or with `useState`), changing it will work correctly due to the cleanup mechanism.\n \n @param props - Provider props including children and required id\n * @returns Provider component that wraps children with map instance identity context\n \n @example\n * Internal usage within BaseMap:\n * ```tsx\n * // BaseMap automatically creates the provider\n * function BaseMap({ id, children, ...props }: BaseMapProps) {\n * return (\n * <div>\n * <MapProvider id={id}>\n * <Deckgl {...props}>\n * {children}\n * </Deckgl>\n * </MapProvider>\n * </div>\n * );\n * }\n * ```\n \n @example\n * With authorization handling - use id in event payloads:\n * ```tsx\n * useOn(MapModeEvents.changeAuthorization, (event) => {\n * const { authId, id } = event.payload;\n * emitDecision({ authId, approved: true, owner: 'tool', id });\n * });\n * ```\n */\nexport function MapProvider({ children, id }: MapProviderProps) {\n // Cleanup when component unmounts\n // State is created automatically on first subscription in useMapMode/useMapCursor\n useEffect(() => {\n return () => {\n clearMapModeState(id);\n clearCursorState(id);\n };\n }, [id]);\n\n return <MapContext.Provider value={id}>{children}</MapContext.Provider>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAa,aAAa,cAA+B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuH9D,SAAgB,YAAY,EAAE,UAAU,MAAwB;AAG9D,iBAAgB;AACd,eAAa;AACX,qBAAkB,GAAG;AACrB,oBAAiB,GAAG;;IAErB,CAAC,GAAG,CAAC;AAER,QAAO,oBAAC,WAAW;EAAS,OAAO;EAAK;GAA+B"}
1	+ {"version":3,"file":"provider.js","names":[],"sources":["../../../src/deckgl/base-map/provider.tsx"],"sourcesContent":["/\n Copyright 2026 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 { createContext, type ReactNode, useEffect } from 'react';\nimport { clearCursorState } from '../../map-cursor/store';\nimport { clearMapModeState } from '../../map-mode/store';\nimport type { UniqueId } from '@accelint/core';\n\n/\n React context for map ID.\n * Use the `useMapMode` hook to access the map mode state.\n /\nexport const MapContext = createContext<UniqueId \| null>(null);\n\n/\n Props for the MapProvider component.\n /\nexport type MapProviderProps = {\n /* Child components that will have access to map mode context /\n children: ReactNode;\n /\n Unique identifier for this map instance.\n \n Used to isolate mode changes between different map instances (e.g., main map vs minimap).\n * This is required and should be provided by the parent component (typically BaseMap).\n \n @example\n * ```tsx\n * // Multiple independent map instances\n * const mainMapId = uuid();\n * const minimapId = uuid();\n \n <MapProvider id={mainMapId}>\n * // Map layers and components\n * </MapProvider>\n \n <MapProvider id={minimapId}>\n * // Minimap layers and components\n * </MapProvider>\n * ```\n /\n id: UniqueId;\n};\n\n/\n Provider component for managing map modes with ownership and authorization.\n \n Note: This provider is used internally by `BaseMap` and should not be used directly.\n * Consumers should pass the `id` prop to `BaseMap`, which will create this provider automatically.\n \n This component uses a hybrid architecture combining React Context (for map instance identity)\n * with module-level state management (for map mode state). The provider:\n * - Provides a unique `id` via Context\n * - Cleans up map mode state when unmounted\n * - Allows components to subscribe to mode changes via `useMapMode` hook (which uses `useSyncExternalStore`)\n \n The module-level state management system implements a state machine for map modes where\n * components can request mode changes with ownership. When a mode is owned by a component,\n * other components must request authorization to change to a different mode. The system handles:\n \n - Automatic mode changes when no ownership conflicts exist\n * - Authorization flow when switching between owned modes\n * - Per-mode ownership tracking that persists throughout the session\n * - Pending request management (one pending request per requester)\n * - Auto-acceptance of first pending request when mode owner returns to default\n * - Auto-rejection of other pending requests when one is approved\n * - Event emission through a centralized event bus\n * - Instance isolation for multiple map scenarios (main map + minimap)\n * - Always initializes in 'default' mode\n \n ## Instance Isolation\n \n Each MapProvider instance operates independently. Mode changes in one instance\n * do not affect other instances, even when multiple maps are rendered on the same page.\n * This enables scenarios like:\n * - Main map in \"drawing\" mode while minimap stays in \"view\" mode\n * - Multiple independent map views with different interaction modes\n \n Events are scoped to specific instances using the `id` prop. The event bus\n * filters events to ensure each provider only responds to events for its own instance.\n \n ## Pending Request Behavior\n \n - Pending requests are stored by requester ID (not mode owner)\n * - Each requester can have only one pending request at a time\n * - New requests from the same requester auto-replace previous requests\n * - Pending requests persist when mode owner switches between their own modes\n * - When any request is approved, all other pending requests are auto-rejected\n * - When mode owner returns to default mode:\n * - If first pending request is for default mode, all pending requests are rejected (already in requested mode)\n * - If first pending request is for a different mode, that request is auto-approved and others are rejected\n \n ## Instance ID Stability and Lifecycle\n \n The provider's cleanup mechanism (via `useEffect`) ensures proper state management:\n * - Map mode state is cleaned up when the provider unmounts\n * - Changing the `id` prop will trigger cleanup of the old state via the effect dependency\n * - State is lazily initialized on first subscription (no manual creation needed)\n \n While the `id` prop should typically remain stable (created as a module-level constant\n * or with `useState`), changing it will work correctly due to the cleanup mechanism.\n \n @param props - Provider props including children and required id\n * @returns Provider component that wraps children with map instance identity context\n \n @example\n * Internal usage within BaseMap:\n * ```tsx\n * // BaseMap automatically creates the provider\n * function BaseMap({ id, children, ...props }: BaseMapProps) {\n * return (\n * <div>\n * <MapProvider id={id}>\n * <Deckgl {...props}>\n * {children}\n * </Deckgl>\n * </MapProvider>\n * </div>\n * );\n * }\n * ```\n \n @example\n * With authorization handling - use id in event payloads:\n * ```tsx\n * useOn(MapModeEvents.changeAuthorization, (event) => {\n * const { authId, id } = event.payload;\n * emitDecision({ authId, approved: true, owner: 'tool', id });\n * });\n * ```\n */\nexport function MapProvider({ children, id }: MapProviderProps) {\n // Cleanup when component unmounts\n // State is created automatically on first subscription in useMapMode/useMapCursor\n useEffect(() => {\n return () => {\n clearMapModeState(id);\n clearCursorState(id);\n };\n }, [id]);\n\n return <MapContext.Provider value={id}>{children}</MapContext.Provider>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAa,aAAa,cAA+B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuH9D,SAAgB,YAAY,EAAE,UAAU,MAAwB;AAG9D,iBAAgB;AACd,eAAa;AACX,qBAAkB,GAAG;AACrB,oBAAiB,GAAG;;IAErB,CAAC,GAAG,CAAC;AAER,QAAO,oBAAC,WAAW;EAAS,OAAO;EAAK;GAA+B"}

package/dist/deckgl/index.js CHANGED Viewed

@@ -11,8 +11,8 @@
  */
-import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
 import { DARK_BASE_MAP_STYLE, LIGHT_BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
+import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
 import { BaseMap } from "./base-map/index.js";
 import { createSavedViewport } from "./saved-viewports/index.js";
 import { DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS } from "./shapes/shared/constants.js";

package/dist/deckgl/saved-viewports/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","names":[],"sources":["../../../src/deckgl/saved-viewports/index.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 {\n type HotkeyOptions,\n type KeyCombination,\n type KeyCombinationId,\n Keycode,\n registerHotkey,\n} from '@accelint/hotkey-manager';\nimport { persist, retrieve, STORAGE_ID } from './storage';\nimport type { MapViewState } from '@deck.gl/core';\nimport type { RequireAllOrNone } from 'type-fest';\n\ntype BaseOptions = {\n uniqueIdentifier?: string;\n threshold?: number;\n getCurrentViewport: () => MapViewState;\n setCurrentViewport: (viewport: MapViewState) => void;\n};\n\ntype PersistOptions = RequireAllOrNone<{\n getSavedViewport: (\n id: KeyCombinationId,\n uniqueIdentifier?: string,\n ) => MapViewState;\n setSavedViewport: (\n id: KeyCombinationId,\n viewport: MapViewState,\n uniqueIdentifier?: string,\n ) => void;\n}>;\n\nexport type SavedViewportOptions = Partial<HotkeyOptions> &\n BaseOptions &\n PersistOptions;\n\nexport const createSavedViewport = (\n options: SavedViewportOptions,\n): ReturnType<typeof registerHotkey> => {\n const setFn = options.setSavedViewport ?? persist;\n const getFn = options.getSavedViewport ?? retrieve;\n\n return registerHotkey({\n id: STORAGE_ID,\n heldThresholdMs: options.threshold,\n key: options.key ?? [\n {\n code: Keycode.Digit0,\n },\n {\n code: Keycode.Digit1,\n },\n {\n code: Keycode.Digit2,\n },\n {\n code: Keycode.Digit3,\n },\n {\n code: Keycode.Digit4,\n },\n {\n code: Keycode.Digit5,\n },\n {\n code: Keycode.Digit6,\n },\n {\n code: Keycode.Digit7,\n },\n {\n code: Keycode.Digit8,\n },\n {\n code: Keycode.Digit9,\n },\n ],\n onKeyHeld: (e: KeyboardEvent, key: KeyCombination) => {\n e.preventDefault();\n const viewport = options.getCurrentViewport();\n setFn(key.id, viewport, options.uniqueIdentifier);\n },\n onKeyUp: (e: KeyboardEvent, key: KeyCombination) => {\n e.preventDefault();\n const viewport = getFn(key.id, options.uniqueIdentifier);\n if (viewport) {\n options.setCurrentViewport(viewport);\n }\n },\n });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AA8CA,MAAa,uBACX,YACsC;CACtC,MAAM,QAAQ,QAAQ,oBAAoB;CAC1C,MAAM,QAAQ,QAAQ,oBAAoB;AAE1C,QAAO,eAAe;EACpB,IAAI;EACJ,iBAAiB,QAAQ;EACzB,KAAK,QAAQ,OAAO;GAClB,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACF;EACD,YAAY,GAAkB,QAAwB;AACpD,KAAE,gBAAgB;GAClB,MAAM,WAAW,QAAQ,oBAAoB;AAC7C,SAAM,IAAI,IAAI,UAAU,QAAQ,iBAAiB;;EAEnD,UAAU,GAAkB,QAAwB;AAClD,KAAE,gBAAgB;GAClB,MAAM,WAAW,MAAM,IAAI,IAAI,QAAQ,iBAAiB;AACxD,OAAI,SACF,SAAQ,mBAAmB,SAAS;;EAGzC,CAAC"}
1	+ {"version":3,"file":"index.js","names":[],"sources":["../../../src/deckgl/saved-viewports/index.ts"],"sourcesContent":["/\n Copyright 2026 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 {\n type HotkeyOptions,\n type KeyCombination,\n type KeyCombinationId,\n Keycode,\n registerHotkey,\n} from '@accelint/hotkey-manager';\nimport { persist, retrieve, STORAGE_ID } from './storage';\nimport type { MapViewState } from '@deck.gl/core';\nimport type { RequireAllOrNone } from 'type-fest';\n\ntype BaseOptions = {\n uniqueIdentifier?: string;\n threshold?: number;\n getCurrentViewport: () => MapViewState;\n setCurrentViewport: (viewport: MapViewState) => void;\n};\n\ntype PersistOptions = RequireAllOrNone<{\n getSavedViewport: (\n id: KeyCombinationId,\n uniqueIdentifier?: string,\n ) => MapViewState;\n setSavedViewport: (\n id: KeyCombinationId,\n viewport: MapViewState,\n uniqueIdentifier?: string,\n ) => void;\n}>;\n\nexport type SavedViewportOptions = Partial<HotkeyOptions> &\n BaseOptions &\n PersistOptions;\n\nexport const createSavedViewport = (\n options: SavedViewportOptions,\n): ReturnType<typeof registerHotkey> => {\n const setFn = options.setSavedViewport ?? persist;\n const getFn = options.getSavedViewport ?? retrieve;\n\n return registerHotkey({\n id: STORAGE_ID,\n heldThresholdMs: options.threshold,\n key: options.key ?? [\n {\n code: Keycode.Digit0,\n },\n {\n code: Keycode.Digit1,\n },\n {\n code: Keycode.Digit2,\n },\n {\n code: Keycode.Digit3,\n },\n {\n code: Keycode.Digit4,\n },\n {\n code: Keycode.Digit5,\n },\n {\n code: Keycode.Digit6,\n },\n {\n code: Keycode.Digit7,\n },\n {\n code: Keycode.Digit8,\n },\n {\n code: Keycode.Digit9,\n },\n ],\n onKeyHeld: (e: KeyboardEvent, key: KeyCombination) => {\n e.preventDefault();\n const viewport = options.getCurrentViewport();\n setFn(key.id, viewport, options.uniqueIdentifier);\n },\n onKeyUp: (e: KeyboardEvent, key: KeyCombination) => {\n e.preventDefault();\n const viewport = getFn(key.id, options.uniqueIdentifier);\n if (viewport) {\n options.setCurrentViewport(viewport);\n }\n },\n });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AA8CA,MAAa,uBACX,YACsC;CACtC,MAAM,QAAQ,QAAQ,oBAAoB;CAC1C,MAAM,QAAQ,QAAQ,oBAAoB;AAE1C,QAAO,eAAe;EACpB,IAAI;EACJ,iBAAiB,QAAQ;EACzB,KAAK,QAAQ,OAAO;GAClB,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACF;EACD,YAAY,GAAkB,QAAwB;AACpD,KAAE,gBAAgB;GAClB,MAAM,WAAW,QAAQ,oBAAoB;AAC7C,SAAM,IAAI,IAAI,UAAU,QAAQ,iBAAiB;;EAEnD,UAAU,GAAkB,QAAwB;AAClD,KAAE,gBAAgB;GAClB,MAAM,WAAW,MAAM,IAAI,IAAI,QAAQ,iBAAiB;AACxD,OAAI,SACF,SAAQ,mBAAmB,SAAS;;EAGzC,CAAC"}