@accelint/map-toolkit 0.6.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @accelint/map-toolkit
 
+## 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
+
+- 4e614fb: Refactor map-toolkit for v1 release:
+
+  **Breaking Changes:**
+  - Rename `useViewportState` → `useMapViewport`
+  - Rename `useCameraState` → `useMapCamera`
+  - Rename `useShapeSelection` → `useSelectShape`
+  - Rename `INITIAL_VIEW_STATE` → `DEFAULT_VIEW_STATE` (in maplibre exports)
+  - Remove `@accelint/map-toolkit/maplibre/constants` export
+
+  **Bug Fixes:**
+  - Fix `useMapCursorEffect` not updating cursor when props change
+  - Fix saved viewports not restoring map position (now uses `CameraEventTypes.setCenter`)
+
+  **Internal Improvements:**
+  - Refactor all stores to use `createMapStore` factory pattern
+  - Hoist `DEFAULT_VIEW_STATE` to `shared/constants`
+  - Replace `console.warn` with `@accelint/logger` for conditional logging
+  - Standardize drawStore to use shared mode-utils
+  - Update saved viewports docs and story to use camera events correctly
+
+### Minor Changes
+
+- fd26776: Add EditShapeLayer for interactive shape editing
+
+  **New features:**
+  - `EditShapeLayer` component for editing existing shapes on the map
+  - `showLabels` prop in `DisplayShapeLayer` now supports `'always' | 'hover' | 'never'` modes for flexible label display (hover mode shows labels only on shape hover)
+  - `useEditShape` hook for managing edit state with `edit()`, `save()`, and `cancel()` controls
+  - Support for all shape types: Point, LineString, Polygon, Rectangle, Circle, and Ellipse
+  - Live measurement tooltips during editing (dimensions and area)
+  - Shift key modifiers: hold for uniform scaling or 45° rotation snapping
+  - ESC key to cancel editing
+  - Locked shape support (`shape.locked` prevents editing)
+
+  **Bug fixes:**
+  - Add `boxZoom` to disabled controls list when Shift key is used for shape operations (prevents map zoom interference)
+
+  **Internal improvements:**
+  - Consolidate tooltip calculation logic into shared geometry measurement utilities
+  - Standardize `mapId` optionality across hooks (optional with context fallback)
+  - Add documentation for modes architecture (README.md in modes directory)
+  - Rename `strokeColor` to `lineColor` and `strokeWidth` to `lineWidth` in style properties to align with deck.gl conventions
+  - Rename `shapeType` to `shape` in Shape type for consistency with deck.gl
+
+- fb3fe97: Add DrawShapeLayer for interactive shape drawing
+
+  **New features:**
+  - `DrawShapeLayer` component for drawing shapes on the map
+  - `useDrawShape` hook for managing drawing state with `draw()` and `cancel()` controls
+  - Support for multiple geometry types: Point, LineString, Polygon, Rectangle, Circle, and Ellipse
+  - Real-time tooltips showing distance/area measurements during drawing
+  - Protected drawing mode (cannot be interrupted by other map mode requests)
+  - Double-click to finish polygons and lines
+  - Shift-to-square constraint when drawing rectangles
+  - Custom styling support (fill/line colors) when initiating drawing
+  - ESC key to cancel drawing
+
+  **Internal improvements:**
+  - Refactor viewport to use shared unit abbreviation map from `shared/units.ts`
+
+### Patch Changes
+
+- 2e6389a: Fixes a regression in viewport size where viewport changes weren't updating
+
 ## 0.6.0
 
 ### Minor 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.4.2, 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
+    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: 0.6.0
+    package/version: 1.1.0
     github.com/project-slug: gohypergiant/standard-toolkit
   links:
     - url: https://github.com/gohypergiant/standard-toolkit/tree/main/packages/map-toolkit
@@ -42,6 +42,7 @@ spec:
     - component:accelint_design-foundation
     - component:accelint_design-toolkit
     - component:accelint_geo
+    - component:accelint_logger
     - component:accelint_postcss-tailwind-css-modules
     - component:accelint_smeegl
     - component:accelint_typescript-config

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/index.d.ts

@@ -11,6 +11,6 @@
  */
 
 import { CameraEventNamespace, CameraEventTypes } from "./events.js";
-import { CameraState, UseCameraStateProps, clearCameraState, useCameraState } from "./use-camera-state.js";
 import { CameraEvent, CameraFitBoundsEvent, CameraResetEvent, CameraSetCenterEvent, CameraSetPitchEvent, CameraSetProjectionEvent, CameraSetRotationEvent, CameraSetViewEvent, CameraSetZoomEvent, ProjectionType, ViewType } from "./types.js";
-export { type CameraEvent, CameraEventNamespace, CameraEventTypes, type CameraFitBoundsEvent, type CameraResetEvent, type CameraSetCenterEvent, type CameraSetPitchEvent, type CameraSetProjectionEvent, type CameraSetRotationEvent, type CameraSetViewEvent, type CameraSetZoomEvent, type CameraState, type ProjectionType, type UseCameraStateProps, type ViewType, clearCameraState, useCameraState };
+import { CameraState, cameraStore, clearCameraState, useMapCamera } from "./store.js";
+export { type CameraEvent, CameraEventNamespace, CameraEventTypes, type CameraFitBoundsEvent, type CameraResetEvent, type CameraSetCenterEvent, type CameraSetPitchEvent, type CameraSetProjectionEvent, type CameraSetRotationEvent, type CameraSetViewEvent, type CameraSetZoomEvent, type CameraState, type ProjectionType, type ViewType, cameraStore, clearCameraState, useMapCamera };

package/dist/camera/index.js

@@ -12,6 +12,6 @@
 
 
 import { CameraEventNamespace, CameraEventTypes } from "./events.js";
-import { clearCameraState, useCameraState } from "./use-camera-state.js";
+import { cameraStore, clearCameraState, useMapCamera } from "./store.js";
 
-export { CameraEventNamespace, CameraEventTypes, clearCameraState, useCameraState };
+export { CameraEventNamespace, CameraEventTypes, cameraStore, clearCameraState, useMapCamera };

package/dist/camera/store.d.ts

@@ -0,0 +1,120 @@
+/*
+ * 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 { ProjectionType, ViewType } from "./types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/camera/store.d.ts
+/**
+ * Camera state for 2D view
+ */
+type CameraState2D = {
+  latitude: number;
+  longitude: number;
+  zoom: number;
+  pitch: 0;
+  rotation: number;
+  projection: 'mercator';
+  view: '2D';
+};
+/**
+ * Camera state for 3D view
+ */
+type CameraState3D = {
+  latitude: number;
+  longitude: number;
+  zoom: number;
+  pitch: 0;
+  rotation: number;
+  projection: 'globe';
+  view: '3D';
+};
+/**
+ * Camera state for 2.5D view
+ */
+type CameraState2Point5D = {
+  latitude: number;
+  longitude: number;
+  zoom: number;
+  pitch: number;
+  rotation: number;
+  projection: 'mercator';
+  view: '2.5D';
+};
+/**
+ * Union type for all camera states
+ */
+type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;
+/**
+ * Actions for camera management
+ */
+type CameraActions = {
+  /** Update camera state directly */
+  setCameraState: (state: Partial<CameraState>) => void;
+};
+/**
+ * Input type for building camera state - simpler than union type
+ */
+type CameraStateInput = {
+  latitude?: number;
+  longitude?: number;
+  zoom?: number;
+  pitch?: number;
+  rotation?: number;
+  projection?: ProjectionType;
+  view?: ViewType;
+};
+/**
+ * Camera store instance
+ */
+declare const cameraStore: MapStore<CameraState, CameraActions>;
+/**
+ * Initialize camera state for a map instance with optional initial values.
+ * Should be called before using the camera store for a given mapId.
+ *
+ * @param mapId - Unique identifier for the map instance
+ * @param initialState - Optional initial camera state
+ */
+declare function initializeCameraState(mapId: UniqueId, initialState?: CameraStateInput): void;
+/**
+ * Hook to subscribe to camera state changes for a specific map.
+ *
+ * @param mapId - Unique identifier for the map instance
+ * @param initialCameraState - Optional initial camera state (only used on first call)
+ * @returns Camera state and setCameraState action
+ *
+ * @example
+ * ```tsx
+ * function MapInfo({ mapId }) {
+ *   const { cameraState, setCameraState } = useMapCamera(mapId);
+ *   return (
+ *     <div>
+ *       Lat: {cameraState.latitude.toFixed(2)}, Lon: {cameraState.longitude.toFixed(2)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useMapCamera(mapId: UniqueId, initialCameraState?: CameraStateInput): {
+  cameraState: CameraState;
+  setCameraState: (state: Partial<CameraState>) => void;
+};
+/**
+ * Manually clear camera state for a specific map instance.
+ *
+ * @param mapId - The unique identifier for the map instance to clear
+ */
+declare function clearCameraState(mapId: UniqueId): void;
+//#endregion
+export { CameraState, cameraStore, clearCameraState, initializeCameraState, useMapCamera };
+//# sourceMappingURL=store.d.ts.map

package/dist/camera/store.js

@@ -0,0 +1,279 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { CameraEventTypes } from "./events.js";
+import { createMapStore } from "../shared/create-map-store.js";
+import { Broadcast } from "@accelint/bus";
+import { fitBounds } from "@math.gl/web-mercator";
+
+//#region src/camera/store.ts
+/**
+* Camera Store
+*
+* Manages camera state (position, zoom, pitch, rotation, projection, view) per map instance.
+* State is updated via bus events or direct actions.
+*
+* @example
+* ```tsx
+* import { cameraStore } from '@accelint/map-toolkit/camera';
+*
+* function MapInfo({ mapId }) {
+*   const { state } = cameraStore.use(mapId);
+*   return (
+*     <div>
+*       Lat: {state.latitude.toFixed(2)}, Lon: {state.longitude.toFixed(2)}
+*     </div>
+*   );
+* }
+* ```
+*/
+const cameraBus = Broadcast.getInstance();
+/**
+* Storage for initial camera state per instance.
+* Used for reset operations to restore to initial values.
+*
+* @internal These caches live outside the store factory because reset operations
+* need access to the original initial values. They are cleaned up via `onCleanup`
+* hook when the store instance is destroyed, and via `clearCameraState()` for
+* manual cleanup. Do NOT use `cameraStore.clear()` directly in tests - use
+* `clearCameraState()` instead to ensure proper cleanup.
+*/
+const initialStateCache = /* @__PURE__ */ new Map();
+/**
+* Track which instances have been initialized.
+* @internal See note on initialStateCache about cleanup.
+*/
+const initializedInstances = /* @__PURE__ */ new Set();
+/**
+* Build a complete camera state from partial input.
+* Returns the appropriate discriminated union variant based on view/projection.
+*/
+function buildCameraState(partial) {
+	const latitude = partial?.latitude ?? 0;
+	const longitude = partial?.longitude ?? 0;
+	const zoom = partial?.zoom ?? 0;
+	const rotation = partial?.rotation ?? 0;
+	const is3D = partial?.view === "3D" || partial?.projection === "globe";
+	const is2Point5D = partial?.view === "2.5D";
+	if (is3D) return {
+		latitude,
+		longitude,
+		zoom,
+		pitch: 0,
+		rotation: 0,
+		projection: "globe",
+		view: "3D"
+	};
+	if (is2Point5D) return {
+		latitude,
+		longitude,
+		zoom,
+		pitch: partial?.pitch ?? 45,
+		rotation,
+		projection: "mercator",
+		view: "2.5D"
+	};
+	return {
+		latitude,
+		longitude,
+		zoom,
+		pitch: 0,
+		rotation,
+		projection: "mercator",
+		view: "2D"
+	};
+}
+/**
+* Default camera state
+*/
+const DEFAULT_CAMERA_STATE = {
+	latitude: 0,
+	longitude: 0,
+	zoom: 0,
+	pitch: 0,
+	rotation: 0,
+	projection: "mercator",
+	view: "2D"
+};
+/**
+* Camera store instance
+*/
+const cameraStore = createMapStore({
+	defaultState: DEFAULT_CAMERA_STATE,
+	actions: (_mapId, { get, replace }) => ({ setCameraState: (updates) => {
+		replace(buildCameraState({
+			...get(),
+			...updates
+		}));
+	} }),
+	bus: (mapId, { get, replace }) => {
+		const unsubReset = cameraBus.on(CameraEventTypes.reset, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const state = get();
+			const initialState = initialStateCache.get(mapId);
+			replace(buildCameraState({
+				latitude: state.latitude,
+				longitude: state.longitude,
+				projection: state.projection,
+				view: state.view,
+				zoom: payload.zoom === false ? state.zoom : initialState?.zoom ?? 0,
+				pitch: payload.pitch === false ? state.pitch : initialState?.pitch ?? 0,
+				rotation: payload.rotation === false ? state.rotation : initialState?.rotation ?? 0
+			}));
+		});
+		const unsubSetCenter = cameraBus.on(CameraEventTypes.setCenter, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const state = get();
+			replace(buildCameraState({
+				...state,
+				latitude: payload.latitude,
+				longitude: payload.longitude,
+				zoom: payload.zoom ?? state.zoom,
+				rotation: payload.heading ?? state.rotation,
+				pitch: payload.pitch ?? state.pitch
+			}));
+		});
+		const unsubFitBounds = cameraBus.on(CameraEventTypes.fitBounds, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const state = get();
+			const { longitude, latitude, zoom } = fitBounds({
+				width: payload.width,
+				height: payload.height,
+				bounds: [[payload.bounds[0], payload.bounds[1]], [payload.bounds[2], payload.bounds[3]]],
+				padding: payload.padding
+			});
+			replace(buildCameraState({
+				...state,
+				latitude,
+				longitude,
+				zoom,
+				rotation: payload.heading ?? state.rotation,
+				pitch: payload.pitch ?? state.pitch
+			}));
+		});
+		const unsubSetProjection = cameraBus.on(CameraEventTypes.setProjection, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const newState = { ...get() };
+			newState.projection = payload.projection;
+			if (payload.projection === "globe") newState.view = "3D";
+			else {
+				newState.view = "2D";
+				newState.pitch = 0;
+			}
+			replace(newState);
+		});
+		const unsubSetView = cameraBus.on(CameraEventTypes.setView, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const newState = { ...get() };
+			newState.view = payload.view;
+			if (payload.view === "3D") {
+				newState.projection = "globe";
+				newState.pitch = 0;
+			} else newState.projection = "mercator";
+			if (payload.view === "2.5D") newState.pitch = 45;
+			replace(newState);
+		});
+		const unsubSetZoom = cameraBus.on(CameraEventTypes.setZoom, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			replace({
+				...get(),
+				zoom: payload.zoom
+			});
+		});
+		const unsubSetRotation = cameraBus.on(CameraEventTypes.setRotation, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const state = get();
+			if (state.view !== "3D") replace({
+				...state,
+				rotation: payload.rotation
+			});
+		});
+		const unsubSetPitch = cameraBus.on(CameraEventTypes.setPitch, ({ payload }) => {
+			if (payload.id !== mapId) return;
+			const state = get();
+			if (state.view === "2.5D") replace({
+				...state,
+				pitch: payload.pitch
+			});
+		});
+		return () => {
+			unsubReset();
+			unsubSetCenter();
+			unsubFitBounds();
+			unsubSetProjection();
+			unsubSetView();
+			unsubSetZoom();
+			unsubSetRotation();
+			unsubSetPitch();
+		};
+	},
+	onCleanup: (mapId) => {
+		initializedInstances.delete(mapId);
+		initialStateCache.delete(mapId);
+	}
+});
+/**
+* Initialize camera state for a map instance with optional initial values.
+* Should be called before using the camera store for a given mapId.
+*
+* @param mapId - Unique identifier for the map instance
+* @param initialState - Optional initial camera state
+*/
+function initializeCameraState(mapId, initialState) {
+	if (initializedInstances.has(mapId)) return;
+	initializedInstances.add(mapId);
+	if (initialState) initialStateCache.set(mapId, initialState);
+	const builtState = buildCameraState(initialState);
+	cameraStore.set(mapId, builtState);
+}
+/**
+* Hook to subscribe to camera state changes for a specific map.
+*
+* @param mapId - Unique identifier for the map instance
+* @param initialCameraState - Optional initial camera state (only used on first call)
+* @returns Camera state and setCameraState action
+*
+* @example
+* ```tsx
+* function MapInfo({ mapId }) {
+*   const { cameraState, setCameraState } = useMapCamera(mapId);
+*   return (
+*     <div>
+*       Lat: {cameraState.latitude.toFixed(2)}, Lon: {cameraState.longitude.toFixed(2)}
+*     </div>
+*   );
+* }
+* ```
+*/
+function useMapCamera(mapId, initialCameraState) {
+	if (initialCameraState && !initializedInstances.has(mapId)) initializeCameraState(mapId, initialCameraState);
+	const { state, setCameraState } = cameraStore.use(mapId);
+	return {
+		cameraState: state,
+		setCameraState
+	};
+}
+/**
+* Manually clear camera state for a specific map instance.
+*
+* @param mapId - The unique identifier for the map instance to clear
+*/
+function clearCameraState(mapId) {
+	initializedInstances.delete(mapId);
+	initialStateCache.delete(mapId);
+	cameraStore.clear(mapId);
+}
+
+//#endregion
+export { cameraStore, clearCameraState, initializeCameraState, useMapCamera };
+//# sourceMappingURL=store.js.map

package/dist/camera/store.js.map

@@ -0,0 +1 @@
+{"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