@accelint/map-toolkit 0.5.0 → 1.0.0

package/dist/packages/hotkey-manager/dist/stores/hotkey-store/index.js

@@ -1,95 +0,0 @@
-/*
- * 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 { keyToString } from "../../lib/key-to-string/index.js";
-import { enableMapSet } from "../../../../../node_modules/.pnpm/immer@10.2.0/node_modules/immer/dist/immer.js";
-import { immer } from "../../../../../node_modules/.pnpm/zustand@5.0.9_@types_react@19.2.7_immer@10.2.0_react@19.2.3_use-sync-external-store@1.6.0_react@19.2.3_/node_modules/zustand/esm/middleware/immer.js";
-import { createStore } from "../../../../../node_modules/.pnpm/zustand@5.0.9_@types_react@19.2.7_immer@10.2.0_react@19.2.3_use-sync-external-store@1.6.0_react@19.2.3_/node_modules/zustand/esm/vanilla.js";
-
-//#region ../hotkey-manager/dist/stores/hotkey-store/index.js
-enableMapSet();
-const hotkeyStore = createStore()(immer((set, get) => ({
-	allHotkeys: /* @__PURE__ */ new Map(),
-	registeredKeyCombinations: /* @__PURE__ */ new Map(),
-	activeKeyCombinations: /* @__PURE__ */ new Map(),
-	hotkeyActivations: /* @__PURE__ */ new Map(),
-	registerHotkey: (config) => set((state) => {
-		if (state.allHotkeys.has(config.id)) throw new TypeError(`Hotkey with id ${config.id} has already been registered.`);
-		state.allHotkeys.set(config.id, config);
-		for (const key of config.key) {
-			if (!config.ignoreConflicts && state.registeredKeyCombinations.has(key.id)) {
-				const ids = state.registeredKeyCombinations.get(key.id);
-				console.warn(`Hotkey with the combination ${keyToString(key)} already registered to ${ids.join(", ")}`);
-			}
-			state.registeredKeyCombinations.set(key.id, (state.registeredKeyCombinations.get(key.id) ?? []).concat(config.id));
-		}
-	}),
-	unregisterHotkey: (id) => set((state) => {
-		removeHotkeyFromRegisteredKeyCombinations(state, id);
-		removeHotkeyFromActiveKeyCombinations(state, id);
-		state.allHotkeys.delete(id);
-	}),
-	activateHotkey: (id, activationSymbol) => set((state) => {
-		const config = state.allHotkeys.get(id);
-		if (!config) return;
-		for (const key of config.key) {
-			const activated = state.activeKeyCombinations.get(key.id) ?? [];
-			if (activated.includes(id)) continue;
-			state.activeKeyCombinations.set(key.id, [...activated, id]);
-		}
-		const activations = state.hotkeyActivations.get(id) ?? [];
-		if (activations.includes(activationSymbol)) return;
-		state.hotkeyActivations.set(id, [...activations, activationSymbol]);
-	}),
-	deactivateHotkey: (id, registerSymbol) => set((state) => {
-		const activations = state.hotkeyActivations.get(id) ?? [];
-		if (!activations.includes(registerSymbol)) return;
-		const newActivations = activations.filter((activation) => activation !== registerSymbol);
-		if (newActivations.length > 0) {
-			state.hotkeyActivations.set(id, newActivations);
-			return;
-		}
-		state.hotkeyActivations.delete(id);
-		removeHotkeyFromActiveKeyCombinations(state, id);
-	}),
-	forceDeactivateHotkey: (id) => set((state) => {
-		state.hotkeyActivations.delete(id);
-		removeHotkeyFromActiveKeyCombinations(state, id);
-	}),
-	getHotkeysForKeyCombination: (keyCombination) => {
-		const state = get();
-		const ids = state.activeKeyCombinations.get(keyCombination);
-		if (!ids) return null;
-		return ids.map((id) => state.allHotkeys.get(id)).filter(Boolean);
-	}
-})));
-function removeHotkeyFromRegisteredKeyCombinations(state, id) {
-	const config = state.allHotkeys.get(id);
-	if (!config) return;
-	for (const key of config.key) {
-		const newRegistered = (state.registeredKeyCombinations.get(key.id) ?? []).filter((configId) => configId !== id);
-		newRegistered.length === 0 ? state.registeredKeyCombinations.delete(key.id) : state.registeredKeyCombinations.set(key.id, newRegistered);
-	}
-}
-function removeHotkeyFromActiveKeyCombinations(state, id) {
-	const config = state.allHotkeys.get(id);
-	if (!config) return;
-	for (const key of config.key) {
-		const newActive = (state.activeKeyCombinations.get(key.id) ?? []).filter((configId) => configId !== id);
-		newActive.length === 0 ? state.activeKeyCombinations.delete(key.id) : state.activeKeyCombinations.set(key.id, newActive);
-	}
-}
-
-//#endregion
-export { hotkeyStore };
-//# sourceMappingURL=index.js.map

package/dist/packages/hotkey-manager/dist/stores/hotkey-store/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../../../../../hotkey-manager/dist/stores/hotkey-store/index.js"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n\nimport { keyToString } from \"../../lib/key-to-string/index.js\";\nimport { enableMapSet } from \"immer\";\nimport { immer } from \"zustand/middleware/immer\";\nimport { createStore } from \"zustand/vanilla\";\n\n//#region src/stores/hotkey-store/index.ts\nenableMapSet();\nconst hotkeyStore = createStore()(immer((set, get) => ({\n\tallHotkeys: /* @__PURE__ */ new Map(),\n\tregisteredKeyCombinations: /* @__PURE__ */ new Map(),\n\tactiveKeyCombinations: /* @__PURE__ */ new Map(),\n\thotkeyActivations: /* @__PURE__ */ new Map(),\n\tregisterHotkey: (config) => set((state) => {\n\t\tif (state.allHotkeys.has(config.id)) throw new TypeError(`Hotkey with id ${config.id} has already been registered.`);\n\t\tstate.allHotkeys.set(config.id, config);\n\t\tfor (const key of config.key) {\n\t\t\tif (!config.ignoreConflicts && state.registeredKeyCombinations.has(key.id)) {\n\t\t\t\tconst ids = state.registeredKeyCombinations.get(key.id);\n\t\t\t\tconsole.warn(`Hotkey with the combination ${keyToString(key)} already registered to ${ids.join(\", \")}`);\n\t\t\t}\n\t\t\tstate.registeredKeyCombinations.set(key.id, (state.registeredKeyCombinations.get(key.id) ?? []).concat(config.id));\n\t\t}\n\t}),\n\tunregisterHotkey: (id) => set((state) => {\n\t\tremoveHotkeyFromRegisteredKeyCombinations(state, id);\n\t\tremoveHotkeyFromActiveKeyCombinations(state, id);\n\t\tstate.allHotkeys.delete(id);\n\t}),\n\tactivateHotkey: (id, activationSymbol) => set((state) => {\n\t\tconst config = state.allHotkeys.get(id);\n\t\tif (!config) return;\n\t\tfor (const key of config.key) {\n\t\t\tconst activated = state.activeKeyCombinations.get(key.id) ?? [];\n\t\t\tif (activated.includes(id)) continue;\n\t\t\tstate.activeKeyCombinations.set(key.id, [...activated, id]);\n\t\t}\n\t\tconst activations = state.hotkeyActivations.get(id) ?? [];\n\t\tif (activations.includes(activationSymbol)) return;\n\t\tstate.hotkeyActivations.set(id, [...activations, activationSymbol]);\n\t}),\n\tdeactivateHotkey: (id, registerSymbol) => set((state) => {\n\t\tconst activations = state.hotkeyActivations.get(id) ?? [];\n\t\tif (!activations.includes(registerSymbol)) return;\n\t\tconst newActivations = activations.filter((activation) => activation !== registerSymbol);\n\t\tif (newActivations.length > 0) {\n\t\t\tstate.hotkeyActivations.set(id, newActivations);\n\t\t\treturn;\n\t\t}\n\t\tstate.hotkeyActivations.delete(id);\n\t\tremoveHotkeyFromActiveKeyCombinations(state, id);\n\t}),\n\tforceDeactivateHotkey: (id) => set((state) => {\n\t\tstate.hotkeyActivations.delete(id);\n\t\tremoveHotkeyFromActiveKeyCombinations(state, id);\n\t}),\n\tgetHotkeysForKeyCombination: (keyCombination) => {\n\t\tconst state = get();\n\t\tconst ids = state.activeKeyCombinations.get(keyCombination);\n\t\tif (!ids) return null;\n\t\treturn ids.map((id) => state.allHotkeys.get(id)).filter(Boolean);\n\t}\n})));\nfunction removeHotkeyFromRegisteredKeyCombinations(state, id) {\n\tconst config = state.allHotkeys.get(id);\n\tif (!config) return;\n\tfor (const key of config.key) {\n\t\tconst newRegistered = (state.registeredKeyCombinations.get(key.id) ?? []).filter((configId) => configId !== id);\n\t\tnewRegistered.length === 0 ? state.registeredKeyCombinations.delete(key.id) : state.registeredKeyCombinations.set(key.id, newRegistered);\n\t}\n}\nfunction removeHotkeyFromActiveKeyCombinations(state, id) {\n\tconst config = state.allHotkeys.get(id);\n\tif (!config) return;\n\tfor (const key of config.key) {\n\t\tconst newActive = (state.activeKeyCombinations.get(key.id) ?? []).filter((configId) => configId !== id);\n\t\tnewActive.length === 0 ? state.activeKeyCombinations.delete(key.id) : state.activeKeyCombinations.set(key.id, newActive);\n\t}\n}\n\n//#endregion\nexport { hotkeyStore };\n//# sourceMappingURL=index.js.map"],"mappings":"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"}

package/dist/viewport/constants.d.ts

@@ -1,11 +0,0 @@
-//#region src/viewport/constants.d.ts
-declare const UNIT_MAP: {
-  readonly km: "kilometers";
-  readonly m: "meters";
-  readonly nm: "nauticalmiles";
-  readonly mi: "miles";
-  readonly ft: "feet";
-};
-//#endregion
-export { UNIT_MAP };
-//# sourceMappingURL=constants.d.ts.map

package/dist/viewport/constants.js

@@ -1,25 +0,0 @@
-/*
- * 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.
- */
-
-
-//#region src/viewport/constants.ts
-const UNIT_MAP = {
-	km: "kilometers",
-	m: "meters",
-	nm: "nauticalmiles",
-	mi: "miles",
-	ft: "feet"
-};
-
-//#endregion
-export { UNIT_MAP };
-//# sourceMappingURL=constants.js.map

package/dist/viewport/constants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../../src/viewport/constants.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 UNIT_MAP = {\n  km: 'kilometers',\n  m: 'meters',\n  nm: 'nauticalmiles',\n  mi: 'miles',\n  ft: 'feet',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,WAAW;CACtB,IAAI;CACJ,GAAG;CACH,IAAI;CACJ,IAAI;CACJ,IAAI;CACL"}

package/dist/viewport/use-viewport-state.d.ts

@@ -1,100 +0,0 @@
-/*
- * 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 { MapViewportPayload } from "../deckgl/base-map/types.js";
-import { useSyncExternalStore } from "react";
-import { UniqueId } from "@accelint/core";
-
-//#region src/viewport/use-viewport-state.d.ts
-type UseViewportStateProps = {
-  instanceId: UniqueId;
-  subscribe?: Parameters<typeof useSyncExternalStore<MapViewportPayload>>[0];
-  getSnapshot?: Parameters<typeof useSyncExternalStore<MapViewportPayload>>[1];
-  getServerSnapshot?: Parameters<typeof useSyncExternalStore<MapViewportPayload>>[2];
-};
-/**
- * Hook to subscribe to viewport state changes for a specific view.
- *
- * By default, subscribes to MapEvents.viewport events from the event bus and
- * automatically cleans up when all subscribers unmount. For advanced use cases,
- * custom subscribe/getSnapshot functions can be provided.
- *
- * A thin wrapper around [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore).
- *
- * @param instanceId - Unique identifier for the viewport to track
- * @param subscribe - Optional custom subscription function
- * @param getSnapshot - Optional custom snapshot getter
- * @param getServerSnapshot - Optional server-side snapshot getter
- * @returns Current viewport state including bounds, latitude, longitude, zoom
- *
- * @example
- * ```tsx
- * function MapInfo({ instanceId }) {
- *   const { bounds, latitude, longitude, zoom } = useViewportState({
- *     instanceId
- *   });
- *
- *   return (
- *     <div>
- *       Lat: {latitude?.toFixed(2)}, Lon: {longitude?.toFixed(2)}, Zoom: {zoom}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With custom subscribe/getSnapshot for advanced use cases
- * function CustomMapInfo() {
- *   const customSubscribe = (onStoreChange) => {
- *     // Custom subscription logic
- *     return () => { // cleanup }
- *   }
- *
- *   const customGetSnapshot = () => {
- *     // Custom snapshot logic
- *     return { latitude: 0, longitude: 0, zoom: 1 };
- *   };
- *
- *   const viewState = useViewportState({
- *     instanceId: 'some-uuid',
- *     subscribe: customSubscribe,
- *     getSnapshot: customGetSnapshot,
- *   });
- *
- *   return <div>Custom viewport state</div>;
- * }
- * ```
- */
-declare function useViewportState({
-  instanceId,
-  subscribe,
-  getSnapshot,
-  getServerSnapshot
-}: UseViewportStateProps): MapViewportPayload;
-/**
- * Manually clear viewport 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 viewport to clear
- *
- * @example
- * ```tsx
- * // Manual cleanup (rarely needed)
- * clearViewportState('my-map-instance');
- * ```
- */
-declare function clearViewportState(instanceId: UniqueId): void;
-//#endregion
-export { UseViewportStateProps, clearViewportState, useViewportState };
-//# sourceMappingURL=use-viewport-state.d.ts.map

package/dist/viewport/use-viewport-state.js

@@ -1,222 +0,0 @@
-/*
- * 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 { MapEvents } from "../deckgl/base-map/events.js";
-import { Broadcast } from "@accelint/bus";
-import { useSyncExternalStore } from "react";
-
-//#region src/viewport/use-viewport-state.ts
-const bus = Broadcast.getInstance();
-/**
-* Store for viewport state keyed by instanceId
-*/
-const viewportStore = /* @__PURE__ */ new Map();
-/**
-* Track React component subscribers per instanceId (for fan-out notifications).
-* Each Set contains onStoreChange callbacks from useSyncExternalStore.
-*/
-const componentSubscribers = /* @__PURE__ */ new Map();
-/**
-* Cache of bus unsubscribe functions (1 per instanceId).
-* This ensures we only have one bus listener per viewport, regardless of
-* how many React components subscribe to it.
-*/
-const busUnsubscribers = /* @__PURE__ */ new Map();
-/**
-* Cache of subscription functions per instanceId to avoid recreating on every render
-*/
-const subscriptionCache = /* @__PURE__ */ new Map();
-/**
-* Cache of snapshot functions per instanceId to maintain referential stability
-*/
-const snapshotCache = /* @__PURE__ */ new Map();
-/**
-* Cache of fallback snapshots per instanceId to maintain referential stability.
-* This prevents unnecessary re-renders when no viewport data exists yet.
-*/
-const fallbackCache = /* @__PURE__ */ new Map();
-/**
-* Ensures a single bus listener exists for the given instanceId.
-* All React subscribers will be notified via fan-out when the bus event fires.
-* This prevents creating N bus listeners for N React components.
-*
-* @param instanceId - The unique identifier for the viewport
-*/
-function ensureBusListener(instanceId) {
-	if (busUnsubscribers.has(instanceId)) return;
-	const unsub = bus.on(MapEvents.viewport, ({ payload }) => {
-		if (instanceId === payload.id) {
-			viewportStore.set(instanceId, payload);
-			const subscribers = componentSubscribers.get(instanceId);
-			if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
-		}
-	});
-	busUnsubscribers.set(instanceId, unsub);
-}
-/**
-* Cleans up the bus listener if no React subscribers remain.
-*
-* @param instanceId - The unique identifier for the viewport
-*/
-function cleanupBusListenerIfNeeded(instanceId) {
-	const subscribers = componentSubscribers.get(instanceId);
-	if (!subscribers || subscribers.size === 0) {
-		const unsub = busUnsubscribers.get(instanceId);
-		if (unsub) {
-			unsub();
-			busUnsubscribers.delete(instanceId);
-		}
-		viewportStore.delete(instanceId);
-		componentSubscribers.delete(instanceId);
-		subscriptionCache.delete(instanceId);
-		snapshotCache.delete(instanceId);
-		fallbackCache.delete(instanceId);
-	}
-}
-/**
-* Creates or retrieves a cached subscription function for a given instanceId.
-* Uses a fan-out pattern: 1 bus listener -> N React subscribers.
-* Automatically cleans up viewport state when the last subscriber unsubscribes.
-*
-* @param instanceId - The unique identifier for the viewport
-* @returns A subscription function for useSyncExternalStore
-*/
-function getOrCreateSubscription(instanceId) {
-	const subscription = subscriptionCache.get(instanceId) ?? ((onStoreChange) => {
-		ensureBusListener(instanceId);
-		let subscriberSet = componentSubscribers.get(instanceId);
-		if (!subscriberSet) {
-			subscriberSet = /* @__PURE__ */ new Set();
-			componentSubscribers.set(instanceId, subscriberSet);
-		}
-		subscriberSet.add(onStoreChange);
-		return () => {
-			const currentSubscriberSet = componentSubscribers.get(instanceId);
-			if (currentSubscriberSet) currentSubscriberSet.delete(onStoreChange);
-			cleanupBusListenerIfNeeded(instanceId);
-		};
-	});
-	subscriptionCache.set(instanceId, subscription);
-	return subscription;
-}
-/**
-* Creates or retrieves a cached snapshot function for a given instanceId.
-* The object returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
-*
-* @param instanceId - The unique identifier for the viewport
-* @returns A snapshot function for useSyncExternalStore
-*/
-function getOrCreateSnapshot(instanceId) {
-	const fallback = fallbackCache.get(instanceId) ?? (() => {
-		const newFallback = {
-			id: instanceId,
-			bounds: void 0,
-			latitude: NaN,
-			longitude: NaN,
-			zoom: NaN,
-			width: 0,
-			height: 0
-		};
-		fallbackCache.set(instanceId, newFallback);
-		return newFallback;
-	})();
-	const snapshot = snapshotCache.get(instanceId) ?? (() => viewportStore.get(instanceId) ?? fallback);
-	snapshotCache.set(instanceId, snapshot);
-	return snapshot;
-}
-/**
-* Hook to subscribe to viewport state changes for a specific view.
-*
-* By default, subscribes to MapEvents.viewport events from the event bus and
-* automatically cleans up when all subscribers unmount. For advanced use cases,
-* custom subscribe/getSnapshot functions can be provided.
-*
-* A thin wrapper around [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore).
-*
-* @param instanceId - Unique identifier for the viewport to track
-* @param subscribe - Optional custom subscription function
-* @param getSnapshot - Optional custom snapshot getter
-* @param getServerSnapshot - Optional server-side snapshot getter
-* @returns Current viewport state including bounds, latitude, longitude, zoom
-*
-* @example
-* ```tsx
-* function MapInfo({ instanceId }) {
-*   const { bounds, latitude, longitude, zoom } = useViewportState({
-*     instanceId
-*   });
-*
-*   return (
-*     <div>
-*       Lat: {latitude?.toFixed(2)}, Lon: {longitude?.toFixed(2)}, Zoom: {zoom}
-*     </div>
-*   );
-* }
-* ```
-*
-* @example
-* ```tsx
-* // With custom subscribe/getSnapshot for advanced use cases
-* function CustomMapInfo() {
-*   const customSubscribe = (onStoreChange) => {
-*     // Custom subscription logic
-*     return () => { // cleanup }
-*   }
-*
-*   const customGetSnapshot = () => {
-*     // Custom snapshot logic
-*     return { latitude: 0, longitude: 0, zoom: 1 };
-*   };
-*
-*   const viewState = useViewportState({
-*     instanceId: 'some-uuid',
-*     subscribe: customSubscribe,
-*     getSnapshot: customGetSnapshot,
-*   });
-*
-*   return <div>Custom viewport state</div>;
-* }
-* ```
-*/
-function useViewportState({ instanceId, subscribe, getSnapshot, getServerSnapshot }) {
-	return useSyncExternalStore(subscribe ?? getOrCreateSubscription(instanceId), getSnapshot ?? getOrCreateSnapshot(instanceId), getServerSnapshot);
-}
-/**
-* Manually clear viewport 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 viewport to clear
-*
-* @example
-* ```tsx
-* // Manual cleanup (rarely needed)
-* clearViewportState('my-map-instance');
-* ```
-*/
-function clearViewportState(instanceId) {
-	const unsub = busUnsubscribers.get(instanceId);
-	if (unsub) {
-		unsub();
-		busUnsubscribers.delete(instanceId);
-	}
-	viewportStore.delete(instanceId);
-	componentSubscribers.delete(instanceId);
-	subscriptionCache.delete(instanceId);
-	snapshotCache.delete(instanceId);
-	fallbackCache.delete(instanceId);
-}
-
-//#endregion
-export { clearViewportState, useViewportState };
-//# sourceMappingURL=use-viewport-state.js.map

package/dist/viewport/use-viewport-state.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-viewport-state.js","names":["newFallback: MapViewportPayload"],"sources":["../../src/viewport/use-viewport-state.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { useSyncExternalStore } from 'react';\nimport { MapEvents } from '../deckgl/base-map/events';\nimport type { UniqueId } from '@accelint/core';\nimport type {\n  MapEventType,\n  MapViewportPayload,\n} from '../deckgl/base-map/types';\n\nconst bus = Broadcast.getInstance<MapEventType>();\n\nexport type UseViewportStateProps = {\n  instanceId: UniqueId;\n  subscribe?: Parameters<typeof useSyncExternalStore<MapViewportPayload>>[0];\n  getSnapshot?: Parameters<typeof useSyncExternalStore<MapViewportPayload>>[1];\n  getServerSnapshot?: Parameters<\n    typeof useSyncExternalStore<MapViewportPayload>\n  >[2];\n};\n\n/**\n * Store for viewport state keyed by instanceId\n */\nconst viewportStore = new Map<UniqueId, MapViewportPayload>();\n\n/**\n * Track React component subscribers per instanceId (for fan-out notifications).\n * Each Set contains onStoreChange callbacks from useSyncExternalStore.\n */\nconst componentSubscribers = new Map<UniqueId, Set<() => void>>();\n\n/**\n * Cache of bus unsubscribe functions (1 per instanceId).\n * This ensures we only have one bus listener per viewport, regardless of\n * how many React components subscribe to it.\n */\nconst busUnsubscribers = new Map<UniqueId, () => void>();\n\ntype Subscription = (onStoreChange: () => void) => () => void;\n/**\n * Cache of subscription functions per instanceId to avoid recreating on every render\n */\nconst subscriptionCache = new Map<UniqueId, Subscription>();\n\n/**\n * Cache of snapshot functions per instanceId to maintain referential stability\n */\nconst snapshotCache = new Map<UniqueId, () => MapViewportPayload>();\n\n/**\n * Cache of fallback snapshots per instanceId to maintain referential stability.\n * This prevents unnecessary re-renders when no viewport data exists yet.\n */\nconst fallbackCache = new Map<UniqueId, MapViewportPayload>();\n\n/**\n * Ensures a single bus listener exists for the given instanceId.\n * All React subscribers will be notified via fan-out when the bus event fires.\n * This prevents creating N bus listeners for N React components.\n *\n * @param instanceId - The unique identifier for the viewport\n */\nfunction ensureBusListener(instanceId: UniqueId): void {\n  if (busUnsubscribers.has(instanceId)) {\n    return; // Already listening\n  }\n\n  const unsub = bus.on(MapEvents.viewport, ({ payload }) => {\n    if (instanceId === payload.id) {\n      // Write to store once\n      viewportStore.set(instanceId, payload);\n\n      // Fan-out: notify all React subscribers\n      const subscribers = componentSubscribers.get(instanceId);\n      if (subscribers) {\n        for (const onStoreChange of subscribers) {\n          onStoreChange();\n        }\n      }\n    }\n  });\n\n  busUnsubscribers.set(instanceId, unsub);\n}\n\n/**\n * Cleans up the bus listener if no React subscribers remain.\n *\n * @param instanceId - The unique identifier for the viewport\n */\nfunction cleanupBusListenerIfNeeded(instanceId: UniqueId): void {\n  const subscribers = componentSubscribers.get(instanceId);\n\n  if (!subscribers || subscribers.size === 0) {\n    // No more React subscribers - clean up bus listener\n    const unsub = busUnsubscribers.get(instanceId);\n    if (unsub) {\n      unsub();\n      busUnsubscribers.delete(instanceId);\n    }\n\n    // Clean up all state\n    viewportStore.delete(instanceId);\n    componentSubscribers.delete(instanceId);\n    subscriptionCache.delete(instanceId);\n    snapshotCache.delete(instanceId);\n    fallbackCache.delete(instanceId);\n  }\n}\n\n/**\n * Creates or retrieves a cached subscription function for a given instanceId.\n * Uses a fan-out pattern: 1 bus listener -> N React subscribers.\n * Automatically cleans up viewport state when the last subscriber unsubscribes.\n *\n * @param instanceId - The unique identifier for the viewport\n * @returns A subscription function for useSyncExternalStore\n */\nfunction getOrCreateSubscription(\n  instanceId: UniqueId,\n): (onStoreChange: () => void) => () => void {\n  const subscription =\n    subscriptionCache.get(instanceId) ??\n    ((onStoreChange: () => void) => {\n      // Ensure single bus listener exists for this instanceId\n      ensureBusListener(instanceId);\n\n      // Get or create the subscriber set for this map instance, then add this component's callback\n      let subscriberSet = componentSubscribers.get(instanceId);\n      if (!subscriberSet) {\n        subscriberSet = new Set();\n        componentSubscribers.set(instanceId, subscriberSet);\n      }\n      subscriberSet.add(onStoreChange);\n\n      // Return cleanup function to remove this component's subscription\n      return () => {\n        const currentSubscriberSet = componentSubscribers.get(instanceId);\n        if (currentSubscriberSet) {\n          currentSubscriberSet.delete(onStoreChange);\n        }\n\n        // Clean up bus listener if this was the last React subscriber\n        cleanupBusListenerIfNeeded(instanceId);\n      };\n    });\n\n  subscriptionCache.set(instanceId, subscription);\n\n  return subscription;\n}\n\n/**\n * Creates or retrieves a cached snapshot function for a given instanceId.\n * The object returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.\n *\n * @param instanceId - The unique identifier for the viewport\n * @returns A snapshot function for useSyncExternalStore\n */\nfunction getOrCreateSnapshot(instanceId: UniqueId): () => MapViewportPayload {\n  // Get or create stable fallback reference for this instanceId\n  const fallback =\n    fallbackCache.get(instanceId) ??\n    (() => {\n      const newFallback: MapViewportPayload = {\n        id: instanceId,\n        bounds: undefined,\n        latitude: Number.NaN,\n        longitude: Number.NaN,\n        zoom: Number.NaN,\n        width: 0,\n        height: 0,\n      };\n      fallbackCache.set(instanceId, newFallback);\n      return newFallback;\n    })();\n\n  const snapshot =\n    snapshotCache.get(instanceId) ??\n    (() => viewportStore.get(instanceId) ?? fallback);\n\n  snapshotCache.set(instanceId, snapshot);\n\n  return snapshot;\n}\n\n/**\n * Hook to subscribe to viewport state changes for a specific view.\n *\n * By default, subscribes to MapEvents.viewport events from the event bus and\n * automatically cleans up when all subscribers unmount. For advanced use cases,\n * custom subscribe/getSnapshot functions can be provided.\n *\n * A thin wrapper around [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore).\n *\n * @param instanceId - Unique identifier for the viewport to track\n * @param subscribe - Optional custom subscription function\n * @param getSnapshot - Optional custom snapshot getter\n * @param getServerSnapshot - Optional server-side snapshot getter\n * @returns Current viewport state including bounds, latitude, longitude, zoom\n *\n * @example\n * ```tsx\n * function MapInfo({ instanceId }) {\n *   const { bounds, latitude, longitude, zoom } = useViewportState({\n *     instanceId\n *   });\n *\n *   return (\n *     <div>\n *       Lat: {latitude?.toFixed(2)}, Lon: {longitude?.toFixed(2)}, Zoom: {zoom}\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With custom subscribe/getSnapshot for advanced use cases\n * function CustomMapInfo() {\n *   const customSubscribe = (onStoreChange) => {\n *     // Custom subscription logic\n *     return () => { // cleanup }\n *   }\n *\n *   const customGetSnapshot = () => {\n *     // Custom snapshot logic\n *     return { latitude: 0, longitude: 0, zoom: 1 };\n *   };\n *\n *   const viewState = useViewportState({\n *     instanceId: 'some-uuid',\n *     subscribe: customSubscribe,\n *     getSnapshot: customGetSnapshot,\n *   });\n *\n *   return <div>Custom viewport state</div>;\n * }\n * ```\n */\nexport function useViewportState({\n  instanceId,\n  subscribe,\n  getSnapshot,\n  getServerSnapshot,\n}: UseViewportStateProps) {\n  return useSyncExternalStore<MapViewportPayload>(\n    subscribe ?? getOrCreateSubscription(instanceId),\n    getSnapshot ?? getOrCreateSnapshot(instanceId),\n    getServerSnapshot,\n  );\n}\n\n/**\n * Manually clear viewport state for a specific instanceId.\n * This is typically not needed as cleanup happens automatically when all subscribers unmount.\n * Use this only in advanced scenarios where manual cleanup is required.\n *\n * @param instanceId - The unique identifier for the viewport to clear\n *\n * @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearViewportState('my-map-instance');\n * ```\n */\nexport function clearViewportState(instanceId: UniqueId): void {\n  // Unsubscribe from bus if listening\n  const unsub = busUnsubscribers.get(instanceId);\n  if (unsub) {\n    unsub();\n    busUnsubscribers.delete(instanceId);\n  }\n\n  // Clear all state\n  viewportStore.delete(instanceId);\n  componentSubscribers.delete(instanceId);\n  subscriptionCache.delete(instanceId);\n  snapshotCache.delete(instanceId);\n  fallbackCache.delete(instanceId);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAqBA,MAAM,MAAM,UAAU,aAA2B;;;;AAcjD,MAAM,gCAAgB,IAAI,KAAmC;;;;;AAM7D,MAAM,uCAAuB,IAAI,KAAgC;;;;;;AAOjE,MAAM,mCAAmB,IAAI,KAA2B;;;;AAMxD,MAAM,oCAAoB,IAAI,KAA6B;;;;AAK3D,MAAM,gCAAgB,IAAI,KAAyC;;;;;AAMnE,MAAM,gCAAgB,IAAI,KAAmC;;;;;;;;AAS7D,SAAS,kBAAkB,YAA4B;AACrD,KAAI,iBAAiB,IAAI,WAAW,CAClC;CAGF,MAAM,QAAQ,IAAI,GAAG,UAAU,WAAW,EAAE,cAAc;AACxD,MAAI,eAAe,QAAQ,IAAI;AAE7B,iBAAc,IAAI,YAAY,QAAQ;GAGtC,MAAM,cAAc,qBAAqB,IAAI,WAAW;AACxD,OAAI,YACF,MAAK,MAAM,iBAAiB,YAC1B,gBAAe;;GAIrB;AAEF,kBAAiB,IAAI,YAAY,MAAM;;;;;;;AAQzC,SAAS,2BAA2B,YAA4B;CAC9D,MAAM,cAAc,qBAAqB,IAAI,WAAW;AAExD,KAAI,CAAC,eAAe,YAAY,SAAS,GAAG;EAE1C,MAAM,QAAQ,iBAAiB,IAAI,WAAW;AAC9C,MAAI,OAAO;AACT,UAAO;AACP,oBAAiB,OAAO,WAAW;;AAIrC,gBAAc,OAAO,WAAW;AAChC,uBAAqB,OAAO,WAAW;AACvC,oBAAkB,OAAO,WAAW;AACpC,gBAAc,OAAO,WAAW;AAChC,gBAAc,OAAO,WAAW;;;;;;;;;;;AAYpC,SAAS,wBACP,YAC2C;CAC3C,MAAM,eACJ,kBAAkB,IAAI,WAAW,MAC/B,kBAA8B;AAE9B,oBAAkB,WAAW;EAG7B,IAAI,gBAAgB,qBAAqB,IAAI,WAAW;AACxD,MAAI,CAAC,eAAe;AAClB,mCAAgB,IAAI,KAAK;AACzB,wBAAqB,IAAI,YAAY,cAAc;;AAErD,gBAAc,IAAI,cAAc;AAGhC,eAAa;GACX,MAAM,uBAAuB,qBAAqB,IAAI,WAAW;AACjE,OAAI,qBACF,sBAAqB,OAAO,cAAc;AAI5C,8BAA2B,WAAW;;;AAI5C,mBAAkB,IAAI,YAAY,aAAa;AAE/C,QAAO;;;;;;;;;AAUT,SAAS,oBAAoB,YAAgD;CAE3E,MAAM,WACJ,cAAc,IAAI,WAAW,WACtB;EACL,MAAMA,cAAkC;GACtC,IAAI;GACJ,QAAQ;GACR,UAAU;GACV,WAAW;GACX,MAAM;GACN,OAAO;GACP,QAAQ;GACT;AACD,gBAAc,IAAI,YAAY,YAAY;AAC1C,SAAO;KACL;CAEN,MAAM,WACJ,cAAc,IAAI,WAAW,WACtB,cAAc,IAAI,WAAW,IAAI;AAE1C,eAAc,IAAI,YAAY,SAAS;AAEvC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDT,SAAgB,iBAAiB,EAC/B,YACA,WACA,aACA,qBACwB;AACxB,QAAO,qBACL,aAAa,wBAAwB,WAAW,EAChD,eAAe,oBAAoB,WAAW,EAC9C,kBACD;;;;;;;;;;;;;;;AAgBH,SAAgB,mBAAmB,YAA4B;CAE7D,MAAM,QAAQ,iBAAiB,IAAI,WAAW;AAC9C,KAAI,OAAO;AACT,SAAO;AACP,mBAAiB,OAAO,WAAW;;AAIrC,eAAc,OAAO,WAAW;AAChC,sBAAqB,OAAO,WAAW;AACvC,mBAAkB,OAAO,WAAW;AACpC,eAAc,OAAO,WAAW;AAChC,eAAc,OAAO,WAAW"}