@accelint/map-toolkit 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @accelint/map-toolkit
 
+## 0.4.0
+### Minor Changes
+
+- 8802d14: Add map-cursor controller to map-toolkit.
+
+### Patch Changes
+
+- 34c42a0: Swap bundling to tsdown and auto generate exports entries in package.json.
+- Updated dependencies [34c42a0]
+  - @accelint/core@0.5.1
+  - @accelint/bus@3.0.1
+  - @accelint/geo@0.4.1
+
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @accelint/geo@0.4.0
+
 ## 0.3.0
 ### Minor Changes
 

package/catalog-info.yaml

@@ -11,15 +11,15 @@ metadata:
 
     Dependencies:
 
-    accelint_biome-config@1.0.2, accelint_bus@3.0.0,
-    accelint_constellation-tracker@1.0.1, accelint_core@0.5.0,
-    accelint_design-foundation@1.0.0, accelint_design-toolkit@8.0.0,
-    accelint_geo@0.3.0, accelint_typescript-config@0.1.4,
+    accelint_biome-config@1.0.2, accelint_bus@3.0.1,
+    accelint_constellation-tracker@1.0.1, accelint_core@0.5.1,
+    accelint_design-foundation@1.0.2, accelint_design-toolkit@8.1.2,
+    accelint_geo@0.4.1, accelint_typescript-config@0.1.4,
     accelint_vitest-config@0.1.5
   annotations:
     backstage.io/edit-url: https://github.com/gohypergiant/standard-toolkit/blob/main/packages/map-toolkit/catalog-info.yaml
     backstage.io/techdocs-ref: dir:.
-    package/version: 0.3.0
+    package/version: 0.4.0
     github.com/project-slug: gohypergiant/standard-toolkit
   links:
     - url: https://github.com/gohypergiant/standard-toolkit/tree/main/packages/map-toolkit

package/dist/cursor-coordinates/index.d.ts

@@ -1,3 +1,14 @@
-export { CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates } from './use-cursor-coordinates.js';
-import '@accelint/geo';
-import '@accelint/core';
+/*
+ * 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 { CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates } from "./use-cursor-coordinates.js";
+export { type CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates };

package/dist/cursor-coordinates/index.js

@@ -1,3 +1,16 @@
-export { clearCursorCoordinateState, useCursorCoordinates } from './use-cursor-coordinates.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+/*
+ * 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 { clearCursorCoordinateState, useCursorCoordinates } from "./use-cursor-coordinates.js";
+
+export { clearCursorCoordinateState, useCursorCoordinates };

package/dist/cursor-coordinates/use-cursor-coordinates.d.ts

@@ -1,6 +1,19 @@
-import { coordinateSystems } from '@accelint/geo';
-import { UniqueId } from '@accelint/core';
+/*
+ * 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 { coordinateSystems } from "@accelint/geo";
+import { UniqueId } from "@accelint/core";
+
+//#region src/cursor-coordinates/use-cursor-coordinates.d.ts
 /**
  * Supported coordinate format types for displaying map coordinates.
  *
@@ -69,8 +82,9 @@ declare function clearCursorCoordinateState(instanceId: UniqueId): void;
  * ```
  */
 declare function useCursorCoordinates(id?: UniqueId): {
-    formattedCoord: string;
-    setFormat: (format: CoordinateFormatTypes) => void;
+  formattedCoord: string;
+  setFormat: (format: CoordinateFormatTypes) => void;
 };
-
-export { type CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates };
+//#endregion
+export { CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates };
+//# sourceMappingURL=use-cursor-coordinates.d.ts.map

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

@@ -1,161 +1,280 @@
-import 'client-only';
-import { Broadcast } from '@accelint/bus';
-import { createCoordinate, coordinateSystems } from '@accelint/geo';
-import { useContext, useSyncExternalStore, useMemo } from 'react';
-import { MapEvents } from '../deckgl/base-map/events.js';
-import { MapContext } from '../deckgl/base-map/provider.js';
+/*
+ * 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 "../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";
+
+//#region src/cursor-coordinates/use-cursor-coordinates.ts
 const bus = Broadcast.getInstance();
 const create = createCoordinate(coordinateSystems.dd, "LONLAT");
 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).
+*
+* @param coord - Tuple of [longitude, latitude] coordinates
+* @returns Formatted string in the format "LON.NNNNNNNN E/W / LAT.NNNNNNNN N/S"
+*/
 const prepareCoord = (coord) => {
-  let lon = coord[0];
-  lon = ((lon + MAX_LONGITUDE) % LONGITUDE_RANGE + LONGITUDE_RANGE) % LONGITUDE_RANGE - MAX_LONGITUDE;
-  const lat = coord[1];
-  const lonStr = `${Math.abs(lon).toFixed(COORDINATE_PRECISION)} ${lon < 0 ? "W" : "E"}`;
-  const latStr = `${Math.abs(lat).toFixed(COORDINATE_PRECISION)} ${lat < 0 ? "S" : "N"}`;
-  return `${lonStr} / ${latStr}`;
+	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);
+	return Array.isArray(value) && value.length === 2 && value.every(Number.isFinite);
 }
+/**
+* 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.
+*
+* @param instanceId - The unique identifier for the map
+*/
 function ensureBusListener(instanceId) {
-  if (busUnsubscribers.has(instanceId)) {
-    return;
-  }
-  const unsub = bus.on(MapEvents.hover, (data) => {
-    const eventId = data.payload.id;
-    if (instanceId !== eventId) {
-      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);
+	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);
 }
+/**
+* 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);
-  }
+	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);
-    }
-    subscriberSet.add(onStoreChange);
-    return () => {
-      const currentSubscriberSet = componentSubscribers.get(instanceId);
-      if (currentSubscriberSet) {
-        currentSubscriberSet.delete(onStoreChange);
-      }
-      cleanupBusListenerIfNeeded(instanceId);
-    };
-  });
-  subscriptionCache.set(instanceId, subscription);
-  return subscription;
+	const subscription = subscriptionCache.get(instanceId) ?? ((onStoreChange) => {
+		ensureBusListener(instanceId);
+		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 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;
-      }
-      const coord = create(prepareCoord(state.coordinate));
-      return coord[state.format]();
-    };
-    snapshotCache.set(instanceId, cached);
-  }
-  return cached;
+	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();
-      }
-    }
-  }
+	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);
+	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.
+*
+* Subscribes to map hover events via the event bus and converts coordinates to various
+* 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.
+*
+* @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
+* @throws {Error} When no id is provided and hook is used outside MapProvider context
+*
+* @example
+* ```tsx
+* import { uuid } from '@accelint/core';
+* import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';
+*
+* const MAP_ID = uuid();
+*
+* function CoordinateDisplay() {
+*   const { formattedCoord, setFormat } = useCursorCoordinates(MAP_ID);
+*
+*   return (
+*     <div>
+*       <select onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}>
+*         <option value="dd">Decimal Degrees</option>
+*         <option value="ddm">Degrees Decimal Minutes</option>
+*         <option value="dms">Degrees Minutes Seconds</option>
+*         <option value="mgrs">MGRS</option>
+*         <option value="utm">UTM</option>
+*       </select>
+*       <div>{formattedCoord}</div>
+*     </div>
+*   );
+* }
+* ```
+*/
 function useCursorCoordinates(id) {
-  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)
-  );
-  return useMemo(
-    () => ({
-      formattedCoord,
-      setFormat: (format) => setFormatForInstance(actualId, format)
-    }),
-    [formattedCoord, actualId]
-  );
+	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));
+	return useMemo(() => ({
+		formattedCoord,
+		setFormat: (format) => setFormatForInstance(actualId, format)
+	}), [formattedCoord, actualId]);
 }
 
+//#endregion
 export { clearCursorCoordinateState, useCursorCoordinates };
-//# sourceMappingURL=use-cursor-coordinates.js.map
 //# sourceMappingURL=use-cursor-coordinates.js.map

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/cursor-coordinates/use-cursor-coordinates.ts"],"names":[],"mappings":"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","file":"use-cursor-coordinates.js","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 * 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  }\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 * 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}\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  const formattedCoord = useSyncExternalStore<string>(\n    getOrCreateSubscription(actualId),\n    getOrCreateSnapshot(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"]}
+{"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":"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"}