@accelint/map-toolkit 0.6.0 → 1.1.0

package/dist/cursor-coordinates/store.js

@@ -0,0 +1,92 @@
+/*
+ * 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 { createMapStore } from "../shared/create-map-store.js";
+import { MapEvents } from "../deckgl/base-map/events.js";
+import { Broadcast } from "@accelint/bus";
+
+//#region src/cursor-coordinates/store.ts
+/**
+* Cursor Coordinates Store
+*
+* Manages cursor coordinate state for map instances using the shared store factory.
+* Subscribes to hover events from the map and stores the current cursor position.
+*
+* @example
+* ```tsx
+* import { cursorCoordinateStore } from './store';
+*
+* // Use in a component
+* function CoordinateDisplay({ mapId }) {
+*   const { state, setFormat } = cursorCoordinateStore.use(mapId);
+*   return <div>{state.coordinate ? `${state.coordinate[0]}, ${state.coordinate[1]}` : '--'}</div>;
+* }
+*
+* // Or use the selector for specific values
+* const coord = cursorCoordinateStore.useSelector(mapId, (s) => s.coordinate);
+* ```
+*/
+const bus = Broadcast.getInstance();
+/**
+* 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);
+}
+/**
+* Cursor coordinates store
+*
+* Stores the current cursor position and display format for each map instance.
+* Automatically subscribes to hover events when first React subscriber mounts.
+*/
+const cursorCoordinateStore = createMapStore({
+	defaultState: {
+		coordinate: null,
+		format: "dd"
+	},
+	actions: (_mapId, { set }) => ({ setFormat: (format) => {
+		set({ format });
+	} }),
+	bus: (mapId, { set }) => {
+		return bus.on(MapEvents.hover, (data) => {
+			if (mapId !== data.payload.id) return;
+			const coords = data.payload.info.coordinate;
+			if (isValidCoordinate(coords)) set({ coordinate: coords });
+			else set({ coordinate: null });
+		});
+	}
+});
+/**
+* Clear cursor coordinate state for a specific map instance.
+* 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) {
+	cursorCoordinateStore.clear(instanceId);
+}
+
+//#endregion
+export { clearCursorCoordinateState, cursorCoordinateStore };
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":[],"sources":["../../src/cursor-coordinates/store.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\n/**\n * Cursor Coordinates Store\n *\n * Manages cursor coordinate state for map instances using the shared store factory.\n * Subscribes to hover events from the map and stores the current cursor position.\n *\n * @example\n * ```tsx\n * import { cursorCoordinateStore } from './store';\n *\n * // Use in a component\n * function CoordinateDisplay({ mapId }) {\n *   const { state, setFormat } = cursorCoordinateStore.use(mapId);\n *   return <div>{state.coordinate ? `${state.coordinate[0]}, ${state.coordinate[1]}` : '--'}</div>;\n * }\n *\n * // Or use the selector for specific values\n * const coord = cursorCoordinateStore.useSelector(mapId, (s) => s.coordinate);\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapEvents } from '../deckgl/base-map/events';\nimport { createMapStore } from '../shared/create-map-store';\nimport type { UniqueId } from '@accelint/core';\nimport type { MapEventType, MapHoverEvent } from '../deckgl/base-map/types';\nimport type { CoordinateFormatTypes, CursorCoordinateState } from './types';\n\nconst bus = Broadcast.getInstance<MapEventType>();\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 * Actions for cursor coordinate management\n */\ntype CursorCoordinateActions = {\n  /** Set the coordinate display format */\n  setFormat: (format: CoordinateFormatTypes) => void;\n};\n\n/**\n * Cursor coordinates store\n *\n * Stores the current cursor position and display format for each map instance.\n * Automatically subscribes to hover events when first React subscriber mounts.\n */\nexport const cursorCoordinateStore = createMapStore<\n  CursorCoordinateState,\n  CursorCoordinateActions\n>({\n  defaultState: {\n    coordinate: null,\n    format: 'dd',\n  },\n\n  actions: (_mapId, { set }) => ({\n    setFormat: (format: CoordinateFormatTypes) => {\n      set({ format });\n    },\n  }),\n\n  bus: (mapId, { set }) => {\n    return bus.on(MapEvents.hover, (data: MapHoverEvent) => {\n      const eventId = data.payload.id;\n\n      // Ignore hover events from other map instances\n      if (mapId !== eventId) {\n        return;\n      }\n\n      const coords = data.payload.info.coordinate;\n\n      // Update coordinate if valid, or clear if invalid\n      if (isValidCoordinate(coords)) {\n        set({ coordinate: coords as [number, number] });\n      } else {\n        set({ coordinate: null });\n      }\n    });\n  },\n});\n\n/**\n * Clear cursor coordinate state for a specific map instance.\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  cursorCoordinateStore.clear(instanceId);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,MAAM,UAAU,aAA2B;;;;;;;;AASjD,SAAS,kBAAkB,OAA6C;AACtE,QACE,MAAM,QAAQ,MAAM,IAAI,MAAM,WAAW,KAAK,MAAM,MAAM,OAAO,SAAS;;;;;;;;AAkB9E,MAAa,wBAAwB,eAGnC;CACA,cAAc;EACZ,YAAY;EACZ,QAAQ;EACT;CAED,UAAU,QAAQ,EAAE,WAAW,EAC7B,YAAY,WAAkC;AAC5C,MAAI,EAAE,QAAQ,CAAC;IAElB;CAED,MAAM,OAAO,EAAE,UAAU;AACvB,SAAO,IAAI,GAAG,UAAU,QAAQ,SAAwB;AAItD,OAAI,UAHY,KAAK,QAAQ,GAI3B;GAGF,MAAM,SAAS,KAAK,QAAQ,KAAK;AAGjC,OAAI,kBAAkB,OAAO,CAC3B,KAAI,EAAE,YAAY,QAA4B,CAAC;OAE/C,KAAI,EAAE,YAAY,MAAM,CAAC;IAE3B;;CAEL,CAAC;;;;;;;;;;;;;;AAeF,SAAgB,2BAA2B,YAA4B;AACrE,uBAAsB,MAAM,WAAW"}

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

@@ -0,0 +1,87 @@
+/*
+ * 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";
+
+//#region src/cursor-coordinates/types.d.ts
+/**
+ * Supported coordinate format types for displaying map coordinates.
+ *
+ * @typedef {'dd' | 'ddm' | 'dms' | 'mgrs' | 'utm'} CoordinateFormatTypes
+ * @property dd - Decimal Degrees (e.g., "45.500000° N, 30.250000° E")
+ * @property ddm - Degrees Decimal Minutes (e.g., "45° 30.0000' N, 30° 15.0000' E")
+ * @property dms - Degrees Minutes Seconds (e.g., "45° 30' 0.00" N, 30° 15' 0.00" E")
+ * @property mgrs - Military Grid Reference System (e.g., "31U DQ 48251 11932")
+ * @property utm - Universal Transverse Mercator (e.g., "31N 448251 5411932")
+ */
+type CoordinateFormatTypes = keyof typeof coordinateSystems;
+/**
+ * Raw coordinate data returned by the hook.
+ * Always in longitude/latitude format, matching the order from map hover events.
+ *
+ * Returns `null` when cursor is not over the map or coordinates are invalid.
+ */
+type RawCoordinate = {
+  /** Longitude value in degrees (-180 to 180, normalized) */
+  longitude: number;
+  /** Latitude value in degrees (-90 to 90) */
+  latitude: number;
+} | null;
+/**
+ * Custom formatter function signature.
+ * Receives the raw coordinate data and returns a formatted string.
+ *
+ * @example
+ * ```typescript
+ * const customFormatter: CoordinateFormatter = (coord) =>
+ *   `Lat: ${coord.latitude.toFixed(6)}° Lng: ${coord.longitude.toFixed(6)}°`;
+ * ```
+ */
+type CoordinateFormatter = (coordinate: NonNullable<RawCoordinate>) => string;
+/**
+ * Options for configuring cursor coordinate behavior.
+ */
+type UseCursorCoordinatesOptions = {
+  /**
+   * Custom formatter function. When provided, this takes precedence
+   * over the built-in format for the `formattedCoord` return value.
+   *
+   * The `setFormat` function still works and affects `currentFormat`,
+   * but won't affect `formattedCoord` when a custom formatter is active.
+   */
+  formatter?: CoordinateFormatter;
+};
+/**
+ * Return type for useCursorCoordinates hook.
+ */
+type UseCursorCoordinatesReturn = {
+  /** Formatted coordinate string using current format or custom formatter */
+  formattedCoord: string;
+  /** Function to change the coordinate format system */
+  setFormat: (format: CoordinateFormatTypes) => void;
+  /** Raw coordinate data (always available when cursor is over map) */
+  rawCoord: RawCoordinate;
+  /** Current active format type */
+  currentFormat: CoordinateFormatTypes;
+};
+/**
+ * Internal state stored for each map instance's cursor coordinates.
+ */
+type CursorCoordinateState = {
+  /** Raw coordinate tuple [longitude, latitude] or null */
+  coordinate: [number, number] | null;
+  /** Current format type */
+  format: CoordinateFormatTypes;
+};
+//#endregion
+export { CoordinateFormatTypes, CoordinateFormatter, CursorCoordinateState, RawCoordinate, UseCursorCoordinatesOptions, UseCursorCoordinatesReturn };
+//# sourceMappingURL=types.d.ts.map

package/dist/cursor-coordinates/types.js

@@ -0,0 +1,12 @@
+/*
+ * 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.
+ */
+

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

@@ -10,35 +10,11 @@
  * governing permissions and limitations under the License.
  */
 
-import { coordinateSystems } from "@accelint/geo";
+import { UseCursorCoordinatesOptions, UseCursorCoordinatesReturn } from "./types.js";
 import { UniqueId } from "@accelint/core";
 
 //#region src/cursor-coordinates/use-cursor-coordinates.d.ts
-/**
- * Supported coordinate format types for displaying map coordinates.
- *
- * @typedef {'dd' | 'ddm' | 'dms' | 'mgrs' | 'utm'} CoordinateFormatTypes
- * @property dd - Decimal Degrees (e.g., "45.50000000 E / 30.25000000 N")
- * @property ddm - Degrees Decimal Minutes (e.g., "45° 30' E / 30° 15' N")
- * @property dms - Degrees Minutes Seconds (e.g., "45° 30' 0\" E / 30° 15' 0\" N")
- * @property mgrs - Military Grid Reference System (e.g., "31U DQ 48251 11932")
- * @property utm - Universal Transverse Mercator (e.g., "31N 448251 5411932")
- */
-type CoordinateFormatTypes = keyof typeof coordinateSystems;
-/**
- * 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');
- * ```
- */
-declare function clearCursorCoordinateState(instanceId: UniqueId): void;
+
 /**
  * React hook that tracks and formats the cursor hover position coordinates on a map.
  *
@@ -46,17 +22,15 @@ declare function clearCursorCoordinateState(instanceId: UniqueId): void;
  * 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';
@@ -80,11 +54,41 @@ declare function clearCursorCoordinateState(instanceId: UniqueId): void;
  *   );
  * }
  * ```
+ *
+ * @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>
+ *   );
+ * }
+ * ```
  */
-declare function useCursorCoordinates(id?: UniqueId): {
-  formattedCoord: string;
-  setFormat: (format: CoordinateFormatTypes) => void;
-};
+declare function useCursorCoordinates(id?: UniqueId, options?: UseCursorCoordinatesOptions): UseCursorCoordinatesReturn;
 //#endregion
-export { CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates };
+export { useCursorCoordinates };
 //# sourceMappingURL=use-cursor-coordinates.d.ts.map