@accelint/map-toolkit 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @accelint/map-toolkit
 
+## 1.2.0
+
+### Minor Changes
+
+- 878bfa6: Refactored the hotkey-manager package to decouple react.
+
+## 1.1.0
+
+### Minor Changes
+
+- 0175dd1: Update useCursorCoordinates to accept a custom formatter and return more information about the raw coordinate.
+
+### Patch Changes
+
+- Updated dependencies [45275c4]
+- Updated dependencies [d328b71]
+  - @accelint/geo@0.5.1
+  - @accelint/logger@0.1.5
+
 ## 1.0.0
 
 ### Major Changes

package/catalog-info.yaml

@@ -11,15 +11,15 @@ metadata:
 
     Dependencies:
 
-    accelint_biome-config@1.0.2, accelint_bus@3.0.2, accelint_core@0.5.2,
-    accelint_design-foundation@2.0.0, accelint_design-toolkit@9.1.1,
-    accelint_geo@0.5.0, accelint_logger@0.1.4,
+    accelint_biome-config@1.1.0, accelint_bus@3.0.2, accelint_core@0.5.2,
+    accelint_design-foundation@2.1.0, accelint_design-toolkit@9.3.0,
+    accelint_geo@0.5.1, accelint_logger@0.1.5,
     accelint_postcss-tailwind-css-modules@1.0.1, accelint_smeegl@0.3.4,
     accelint_typescript-config@0.1.4, accelint_vitest-config@0.1.6
   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: 1.0.0
+    package/version: 1.2.0
     github.com/project-slug: gohypergiant/standard-toolkit
   links:
     - url: https://github.com/gohypergiant/standard-toolkit/tree/main/packages/map-toolkit

package/dist/camera/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../../src/camera/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 CameraEventNamespace = 'camera';\n\nexport const CameraEventTypes = {\n  setView: `${CameraEventNamespace}:setView`,\n  setProjection: `${CameraEventNamespace}:setProjection`,\n  setZoom: `${CameraEventNamespace}:setZoom`,\n  setRotation: `${CameraEventNamespace}:setRotation`,\n  setPitch: `${CameraEventNamespace}:setPitch`,\n  setCenter: `${CameraEventNamespace}:setCenter`,\n  fitBounds: `${CameraEventNamespace}:fitBounds`,\n  reset: `${CameraEventNamespace}:reset`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,uBAAuB;AAEpC,MAAa,mBAAmB;CAC9B,SAAS,GAAG,qBAAqB;CACjC,eAAe,GAAG,qBAAqB;CACvC,SAAS,GAAG,qBAAqB;CACjC,aAAa,GAAG,qBAAqB;CACrC,UAAU,GAAG,qBAAqB;CAClC,WAAW,GAAG,qBAAqB;CACnC,WAAW,GAAG,qBAAqB;CACnC,OAAO,GAAG,qBAAqB;CAChC"}
+{"version":3,"file":"events.js","names":[],"sources":["../../src/camera/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 CameraEventNamespace = 'camera';\n\nexport const CameraEventTypes = {\n  setView: `${CameraEventNamespace}:setView`,\n  setProjection: `${CameraEventNamespace}:setProjection`,\n  setZoom: `${CameraEventNamespace}:setZoom`,\n  setRotation: `${CameraEventNamespace}:setRotation`,\n  setPitch: `${CameraEventNamespace}:setPitch`,\n  setCenter: `${CameraEventNamespace}:setCenter`,\n  fitBounds: `${CameraEventNamespace}:fitBounds`,\n  reset: `${CameraEventNamespace}:reset`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,uBAAuB;AAEpC,MAAa,mBAAmB;CAC9B,SAAS,GAAG,qBAAqB;CACjC,eAAe,GAAG,qBAAqB;CACvC,SAAS,GAAG,qBAAqB;CACjC,aAAa,GAAG,qBAAqB;CACrC,UAAU,GAAG,qBAAqB;CAClC,WAAW,GAAG,qBAAqB;CACnC,WAAW,GAAG,qBAAqB;CACnC,OAAO,GAAG,qBAAqB;CAChC"}

package/dist/camera/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","names":["DEFAULT_CAMERA_STATE: CameraState"],"sources":["../../src/camera/store.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\n/**\n * Camera Store\n *\n * Manages camera state (position, zoom, pitch, rotation, projection, view) per map instance.\n * State is updated via bus events or direct actions.\n *\n * @example\n * ```tsx\n * import { cameraStore } from '@accelint/map-toolkit/camera';\n *\n * function MapInfo({ mapId }) {\n *   const { state } = cameraStore.use(mapId);\n *   return (\n *     <div>\n *       Lat: {state.latitude.toFixed(2)}, Lon: {state.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { fitBounds } from '@math.gl/web-mercator';\nimport { createMapStore } from '../shared/create-map-store';\nimport { CameraEventTypes } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { CameraEvent, ProjectionType, ViewType } from './types';\n\nconst cameraBus = Broadcast.getInstance<CameraEvent>();\n\n/**\n * Camera state for 2D view\n */\ntype CameraState2D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'mercator';\n  view: '2D';\n};\n\n/**\n * Camera state for 3D view\n */\ntype CameraState3D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'globe';\n  view: '3D';\n};\n\n/**\n * Camera state for 2.5D view\n */\ntype CameraState2Point5D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: number;\n  rotation: number;\n  projection: 'mercator';\n  view: '2.5D';\n};\n\n/**\n * Union type for all camera states\n */\nexport type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;\n\n/**\n * Actions for camera management\n */\ntype CameraActions = {\n  /** Update camera state directly */\n  setCameraState: (state: Partial<CameraState>) => void;\n};\n\n/**\n * Storage for initial camera state per instance.\n * Used for reset operations to restore to initial values.\n *\n * @internal These caches live outside the store factory because reset operations\n * need access to the original initial values. They are cleaned up via `onCleanup`\n * hook when the store instance is destroyed, and via `clearCameraState()` for\n * manual cleanup. Do NOT use `cameraStore.clear()` directly in tests - use\n * `clearCameraState()` instead to ensure proper cleanup.\n */\nconst initialStateCache = new Map<UniqueId, CameraStateInput>();\n\n/**\n * Track which instances have been initialized.\n * @internal See note on initialStateCache about cleanup.\n */\nconst initializedInstances = new Set<UniqueId>();\n\n/**\n * Input type for building camera state - simpler than union type\n */\ntype CameraStateInput = {\n  latitude?: number;\n  longitude?: number;\n  zoom?: number;\n  pitch?: number;\n  rotation?: number;\n  projection?: ProjectionType;\n  view?: ViewType;\n};\n\n/**\n * Build a complete camera state from partial input.\n * Returns the appropriate discriminated union variant based on view/projection.\n */\nfunction buildCameraState(partial?: CameraStateInput): CameraState {\n  const latitude = partial?.latitude ?? 0;\n  const longitude = partial?.longitude ?? 0;\n  const zoom = partial?.zoom ?? 0;\n  const rotation = partial?.rotation ?? 0;\n\n  // Determine which variant to build based on view/projection\n  const is3D = partial?.view === '3D' || partial?.projection === 'globe';\n  const is2Point5D = partial?.view === '2.5D';\n\n  if (is3D) {\n    // 3D view: globe projection, no pitch, no rotation\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: 0,\n      rotation: 0,\n      projection: 'globe',\n      view: '3D',\n    } satisfies CameraState3D;\n  }\n\n  if (is2Point5D) {\n    // 2.5D view: mercator projection, variable pitch\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: partial?.pitch ?? 45,\n      rotation,\n      projection: 'mercator',\n      view: '2.5D',\n    } satisfies CameraState2Point5D;\n  }\n\n  // Default: 2D view, mercator projection, no pitch\n  return {\n    latitude,\n    longitude,\n    zoom,\n    pitch: 0,\n    rotation,\n    projection: 'mercator',\n    view: '2D',\n  } satisfies CameraState2D;\n}\n\n/**\n * Default camera state\n */\nconst DEFAULT_CAMERA_STATE: CameraState = {\n  latitude: 0,\n  longitude: 0,\n  zoom: 0,\n  pitch: 0,\n  rotation: 0,\n  projection: 'mercator',\n  view: '2D',\n};\n\n/**\n * Camera store instance\n */\nexport const cameraStore = createMapStore<CameraState, CameraActions>({\n  defaultState: DEFAULT_CAMERA_STATE,\n\n  actions: (_mapId, { get, replace }) => ({\n    setCameraState: (updates: Partial<CameraState>) => {\n      const currentState = get();\n      // Use buildCameraState to ensure proper discriminated union type\n      replace(buildCameraState({ ...currentState, ...updates }));\n    },\n  }),\n\n  bus: (mapId, { get, replace }) => {\n    const unsubReset = cameraBus.on(CameraEventTypes.reset, ({ payload }) => {\n      if (payload.id !== mapId) {\n        return;\n      }\n\n      const state = get();\n      const initialState = initialStateCache.get(mapId);\n      const newState = buildCameraState({\n        latitude: state.latitude,\n        longitude: state.longitude,\n        projection: state.projection,\n        view: state.view,\n        zoom: payload.zoom === false ? state.zoom : (initialState?.zoom ?? 0),\n        pitch:\n          payload.pitch === false ? state.pitch : (initialState?.pitch ?? 0),\n        rotation:\n          payload.rotation === false\n            ? state.rotation\n            : (initialState?.rotation ?? 0),\n      });\n\n      replace(newState);\n    });\n\n    const unsubSetCenter = cameraBus.on(\n      CameraEventTypes.setCenter,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace(\n          buildCameraState({\n            ...state,\n            latitude: payload.latitude,\n            longitude: payload.longitude,\n            zoom: payload.zoom ?? state.zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubFitBounds = cameraBus.on(\n      CameraEventTypes.fitBounds,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const { longitude, latitude, zoom } = fitBounds({\n          width: payload.width,\n          height: payload.height,\n          bounds: [\n            [payload.bounds[0], payload.bounds[1]],\n            [payload.bounds[2], payload.bounds[3]],\n          ],\n          padding: payload.padding,\n        });\n\n        replace(\n          buildCameraState({\n            ...state,\n            latitude,\n            longitude,\n            zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubSetProjection = cameraBus.on(\n      CameraEventTypes.setProjection,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.projection = payload.projection;\n        if (payload.projection === 'globe') {\n          newState.view = '3D';\n        } else {\n          newState.view = '2D';\n          newState.pitch = 0;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetView = cameraBus.on(\n      CameraEventTypes.setView,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.view = payload.view;\n        if (payload.view === '3D') {\n          newState.projection = 'globe';\n          newState.pitch = 0;\n        } else {\n          newState.projection = 'mercator';\n        }\n\n        if (payload.view === '2.5D') {\n          newState.pitch = 45;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetZoom = cameraBus.on(\n      CameraEventTypes.setZoom,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace({ ...state, zoom: payload.zoom });\n      },\n    );\n\n    const unsubSetRotation = cameraBus.on(\n      CameraEventTypes.setRotation,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view !== '3D') {\n          replace({ ...state, rotation: payload.rotation });\n        }\n      },\n    );\n\n    const unsubSetPitch = cameraBus.on(\n      CameraEventTypes.setPitch,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view === '2.5D') {\n          replace({ ...state, pitch: payload.pitch });\n        }\n      },\n    );\n\n    return () => {\n      unsubReset();\n      unsubSetCenter();\n      unsubFitBounds();\n      unsubSetProjection();\n      unsubSetView();\n      unsubSetZoom();\n      unsubSetRotation();\n      unsubSetPitch();\n    };\n  },\n\n  onCleanup: (mapId) => {\n    initializedInstances.delete(mapId);\n    initialStateCache.delete(mapId);\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Initialize camera state for a map instance with optional initial values.\n * Should be called before using the camera store for a given mapId.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialState - Optional initial camera state\n */\nexport function initializeCameraState(\n  mapId: UniqueId,\n  initialState?: CameraStateInput,\n): void {\n  if (initializedInstances.has(mapId)) {\n    return; // Already initialized\n  }\n\n  initializedInstances.add(mapId);\n  if (initialState) {\n    initialStateCache.set(mapId, initialState);\n  }\n  const builtState = buildCameraState(initialState);\n  cameraStore.set(mapId, builtState);\n}\n\n/**\n * Hook to subscribe to camera state changes for a specific map.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialCameraState - Optional initial camera state (only used on first call)\n * @returns Camera state and setCameraState action\n *\n * @example\n * ```tsx\n * function MapInfo({ mapId }) {\n *   const { cameraState, setCameraState } = useMapCamera(mapId);\n *   return (\n *     <div>\n *       Lat: {cameraState.latitude.toFixed(2)}, Lon: {cameraState.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useMapCamera(\n  mapId: UniqueId,\n  initialCameraState?: CameraStateInput,\n): {\n  cameraState: CameraState;\n  setCameraState: (state: Partial<CameraState>) => void;\n} {\n  // Initialize on first use if initial state provided\n  if (initialCameraState && !initializedInstances.has(mapId)) {\n    initializeCameraState(mapId, initialCameraState);\n  }\n\n  const { state, setCameraState } = cameraStore.use(mapId);\n\n  return { cameraState: state, setCameraState };\n}\n\n/**\n * Manually clear camera state for a specific map instance.\n *\n * @param mapId - The unique identifier for the map instance to clear\n */\nexport function clearCameraState(mapId: UniqueId): void {\n  initializedInstances.delete(mapId);\n  initialStateCache.delete(mapId);\n  cameraStore.clear(mapId);\n}\n"],"mappings":"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"}
+{"version":3,"file":"store.js","names":["DEFAULT_CAMERA_STATE: CameraState"],"sources":["../../src/camera/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 * Camera Store\n *\n * Manages camera state (position, zoom, pitch, rotation, projection, view) per map instance.\n * State is updated via bus events or direct actions.\n *\n * @example\n * ```tsx\n * import { cameraStore } from '@accelint/map-toolkit/camera';\n *\n * function MapInfo({ mapId }) {\n *   const { state } = cameraStore.use(mapId);\n *   return (\n *     <div>\n *       Lat: {state.latitude.toFixed(2)}, Lon: {state.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { fitBounds } from '@math.gl/web-mercator';\nimport { createMapStore } from '../shared/create-map-store';\nimport { CameraEventTypes } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { CameraEvent, ProjectionType, ViewType } from './types';\n\nconst cameraBus = Broadcast.getInstance<CameraEvent>();\n\n/**\n * Camera state for 2D view\n */\ntype CameraState2D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'mercator';\n  view: '2D';\n};\n\n/**\n * Camera state for 3D view\n */\ntype CameraState3D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'globe';\n  view: '3D';\n};\n\n/**\n * Camera state for 2.5D view\n */\ntype CameraState2Point5D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: number;\n  rotation: number;\n  projection: 'mercator';\n  view: '2.5D';\n};\n\n/**\n * Union type for all camera states\n */\nexport type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;\n\n/**\n * Actions for camera management\n */\ntype CameraActions = {\n  /** Update camera state directly */\n  setCameraState: (state: Partial<CameraState>) => void;\n};\n\n/**\n * Storage for initial camera state per instance.\n * Used for reset operations to restore to initial values.\n *\n * @internal These caches live outside the store factory because reset operations\n * need access to the original initial values. They are cleaned up via `onCleanup`\n * hook when the store instance is destroyed, and via `clearCameraState()` for\n * manual cleanup. Do NOT use `cameraStore.clear()` directly in tests - use\n * `clearCameraState()` instead to ensure proper cleanup.\n */\nconst initialStateCache = new Map<UniqueId, CameraStateInput>();\n\n/**\n * Track which instances have been initialized.\n * @internal See note on initialStateCache about cleanup.\n */\nconst initializedInstances = new Set<UniqueId>();\n\n/**\n * Input type for building camera state - simpler than union type\n */\ntype CameraStateInput = {\n  latitude?: number;\n  longitude?: number;\n  zoom?: number;\n  pitch?: number;\n  rotation?: number;\n  projection?: ProjectionType;\n  view?: ViewType;\n};\n\n/**\n * Build a complete camera state from partial input.\n * Returns the appropriate discriminated union variant based on view/projection.\n */\nfunction buildCameraState(partial?: CameraStateInput): CameraState {\n  const latitude = partial?.latitude ?? 0;\n  const longitude = partial?.longitude ?? 0;\n  const zoom = partial?.zoom ?? 0;\n  const rotation = partial?.rotation ?? 0;\n\n  // Determine which variant to build based on view/projection\n  const is3D = partial?.view === '3D' || partial?.projection === 'globe';\n  const is2Point5D = partial?.view === '2.5D';\n\n  if (is3D) {\n    // 3D view: globe projection, no pitch, no rotation\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: 0,\n      rotation: 0,\n      projection: 'globe',\n      view: '3D',\n    } satisfies CameraState3D;\n  }\n\n  if (is2Point5D) {\n    // 2.5D view: mercator projection, variable pitch\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: partial?.pitch ?? 45,\n      rotation,\n      projection: 'mercator',\n      view: '2.5D',\n    } satisfies CameraState2Point5D;\n  }\n\n  // Default: 2D view, mercator projection, no pitch\n  return {\n    latitude,\n    longitude,\n    zoom,\n    pitch: 0,\n    rotation,\n    projection: 'mercator',\n    view: '2D',\n  } satisfies CameraState2D;\n}\n\n/**\n * Default camera state\n */\nconst DEFAULT_CAMERA_STATE: CameraState = {\n  latitude: 0,\n  longitude: 0,\n  zoom: 0,\n  pitch: 0,\n  rotation: 0,\n  projection: 'mercator',\n  view: '2D',\n};\n\n/**\n * Camera store instance\n */\nexport const cameraStore = createMapStore<CameraState, CameraActions>({\n  defaultState: DEFAULT_CAMERA_STATE,\n\n  actions: (_mapId, { get, replace }) => ({\n    setCameraState: (updates: Partial<CameraState>) => {\n      const currentState = get();\n      // Use buildCameraState to ensure proper discriminated union type\n      replace(buildCameraState({ ...currentState, ...updates }));\n    },\n  }),\n\n  bus: (mapId, { get, replace }) => {\n    const unsubReset = cameraBus.on(CameraEventTypes.reset, ({ payload }) => {\n      if (payload.id !== mapId) {\n        return;\n      }\n\n      const state = get();\n      const initialState = initialStateCache.get(mapId);\n      const newState = buildCameraState({\n        latitude: state.latitude,\n        longitude: state.longitude,\n        projection: state.projection,\n        view: state.view,\n        zoom: payload.zoom === false ? state.zoom : (initialState?.zoom ?? 0),\n        pitch:\n          payload.pitch === false ? state.pitch : (initialState?.pitch ?? 0),\n        rotation:\n          payload.rotation === false\n            ? state.rotation\n            : (initialState?.rotation ?? 0),\n      });\n\n      replace(newState);\n    });\n\n    const unsubSetCenter = cameraBus.on(\n      CameraEventTypes.setCenter,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace(\n          buildCameraState({\n            ...state,\n            latitude: payload.latitude,\n            longitude: payload.longitude,\n            zoom: payload.zoom ?? state.zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubFitBounds = cameraBus.on(\n      CameraEventTypes.fitBounds,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const { longitude, latitude, zoom } = fitBounds({\n          width: payload.width,\n          height: payload.height,\n          bounds: [\n            [payload.bounds[0], payload.bounds[1]],\n            [payload.bounds[2], payload.bounds[3]],\n          ],\n          padding: payload.padding,\n        });\n\n        replace(\n          buildCameraState({\n            ...state,\n            latitude,\n            longitude,\n            zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubSetProjection = cameraBus.on(\n      CameraEventTypes.setProjection,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.projection = payload.projection;\n        if (payload.projection === 'globe') {\n          newState.view = '3D';\n        } else {\n          newState.view = '2D';\n          newState.pitch = 0;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetView = cameraBus.on(\n      CameraEventTypes.setView,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.view = payload.view;\n        if (payload.view === '3D') {\n          newState.projection = 'globe';\n          newState.pitch = 0;\n        } else {\n          newState.projection = 'mercator';\n        }\n\n        if (payload.view === '2.5D') {\n          newState.pitch = 45;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetZoom = cameraBus.on(\n      CameraEventTypes.setZoom,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace({ ...state, zoom: payload.zoom });\n      },\n    );\n\n    const unsubSetRotation = cameraBus.on(\n      CameraEventTypes.setRotation,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view !== '3D') {\n          replace({ ...state, rotation: payload.rotation });\n        }\n      },\n    );\n\n    const unsubSetPitch = cameraBus.on(\n      CameraEventTypes.setPitch,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view === '2.5D') {\n          replace({ ...state, pitch: payload.pitch });\n        }\n      },\n    );\n\n    return () => {\n      unsubReset();\n      unsubSetCenter();\n      unsubFitBounds();\n      unsubSetProjection();\n      unsubSetView();\n      unsubSetZoom();\n      unsubSetRotation();\n      unsubSetPitch();\n    };\n  },\n\n  onCleanup: (mapId) => {\n    initializedInstances.delete(mapId);\n    initialStateCache.delete(mapId);\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Initialize camera state for a map instance with optional initial values.\n * Should be called before using the camera store for a given mapId.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialState - Optional initial camera state\n */\nexport function initializeCameraState(\n  mapId: UniqueId,\n  initialState?: CameraStateInput,\n): void {\n  if (initializedInstances.has(mapId)) {\n    return; // Already initialized\n  }\n\n  initializedInstances.add(mapId);\n  if (initialState) {\n    initialStateCache.set(mapId, initialState);\n  }\n  const builtState = buildCameraState(initialState);\n  cameraStore.set(mapId, builtState);\n}\n\n/**\n * Hook to subscribe to camera state changes for a specific map.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialCameraState - Optional initial camera state (only used on first call)\n * @returns Camera state and setCameraState action\n *\n * @example\n * ```tsx\n * function MapInfo({ mapId }) {\n *   const { cameraState, setCameraState } = useMapCamera(mapId);\n *   return (\n *     <div>\n *       Lat: {cameraState.latitude.toFixed(2)}, Lon: {cameraState.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useMapCamera(\n  mapId: UniqueId,\n  initialCameraState?: CameraStateInput,\n): {\n  cameraState: CameraState;\n  setCameraState: (state: Partial<CameraState>) => void;\n} {\n  // Initialize on first use if initial state provided\n  if (initialCameraState && !initializedInstances.has(mapId)) {\n    initializeCameraState(mapId, initialCameraState);\n  }\n\n  const { state, setCameraState } = cameraStore.use(mapId);\n\n  return { cameraState: state, setCameraState };\n}\n\n/**\n * Manually clear camera state for a specific map instance.\n *\n * @param mapId - The unique identifier for the map instance to clear\n */\nexport function clearCameraState(mapId: UniqueId): void {\n  initializedInstances.delete(mapId);\n  initialStateCache.delete(mapId);\n  cameraStore.clear(mapId);\n}\n"],"mappings":"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"}

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

@@ -10,5 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates } from "./use-cursor-coordinates.js";
-export { type CoordinateFormatTypes, clearCursorCoordinateState, useCursorCoordinates };
+import { CoordinateFormatTypes, CoordinateFormatter, CursorCoordinateState, RawCoordinate, UseCursorCoordinatesOptions, UseCursorCoordinatesReturn } from "./types.js";
+import { clearCursorCoordinateState, cursorCoordinateStore } from "./store.js";
+import { useCursorCoordinates } from "./use-cursor-coordinates.js";
+export { type CoordinateFormatTypes, type CoordinateFormatter, type CursorCoordinateState, type RawCoordinate, type UseCursorCoordinatesOptions, type UseCursorCoordinatesReturn, clearCursorCoordinateState, cursorCoordinateStore, useCursorCoordinates };

package/dist/cursor-coordinates/index.js

@@ -11,6 +11,7 @@
  */
 
 
-import { clearCursorCoordinateState, useCursorCoordinates } from "./use-cursor-coordinates.js";
+import { clearCursorCoordinateState, cursorCoordinateStore } from "./store.js";
+import { useCursorCoordinates } from "./use-cursor-coordinates.js";
 
-export { clearCursorCoordinateState, useCursorCoordinates };
+export { clearCursorCoordinateState, cursorCoordinateStore, useCursorCoordinates };

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

@@ -0,0 +1,48 @@
+/*
+ * 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 { MapStore } from "../shared/create-map-store.js";
+import { CoordinateFormatTypes, CursorCoordinateState } from "./types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/cursor-coordinates/store.d.ts
+/**
+ * Actions for cursor coordinate management
+ */
+type CursorCoordinateActions = {
+  /** Set the coordinate display format */
+  setFormat: (format: CoordinateFormatTypes) => void;
+};
+/**
+ * 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.
+ */
+declare const cursorCoordinateStore: MapStore<CursorCoordinateState, CursorCoordinateActions>;
+/**
+ * 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');
+ * ```
+ */
+declare function clearCursorCoordinateState(instanceId: UniqueId): void;
+//#endregion
+export { clearCursorCoordinateState, cursorCoordinateStore };
+//# sourceMappingURL=store.d.ts.map

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