@accelint/map-toolkit 0.6.0 → 1.0.0

package/dist/shared/constants.d.ts

@@ -0,0 +1,19 @@
+//#region src/shared/constants.d.ts
+/**
+ * Default view state for map initialization.
+ * Used by both BaseMap (deck.gl) and MapLibre components.
+ *
+ * Centered on Washington D.C. at zoom level 4 (continental US view).
+ */
+declare const DEFAULT_VIEW_STATE: {
+  longitude: number;
+  latitude: number;
+  zoom: number;
+  minZoom: number;
+  maxZoom: number;
+  pitch: number;
+  bearing: number;
+};
+//#endregion
+export { DEFAULT_VIEW_STATE };
+//# sourceMappingURL=constants.d.ts.map

package/dist/shared/constants.js

@@ -0,0 +1,33 @@
+/*
+ * 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/shared/constants.ts
+/**
+* Default view state for map initialization.
+* Used by both BaseMap (deck.gl) and MapLibre components.
+*
+* Centered on Washington D.C. at zoom level 4 (continental US view).
+*/
+const DEFAULT_VIEW_STATE = {
+	longitude: -77.0369,
+	latitude: 38.9072,
+	zoom: 4,
+	minZoom: 1,
+	maxZoom: 22,
+	pitch: 0,
+	bearing: 0
+};
+
+//#endregion
+export { DEFAULT_VIEW_STATE };
+//# sourceMappingURL=constants.js.map

package/dist/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../src/shared/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\n/**\n * Default view state for map initialization.\n * Used by both BaseMap (deck.gl) and MapLibre components.\n *\n * Centered on Washington D.C. at zoom level 4 (continental US view).\n */\nexport const DEFAULT_VIEW_STATE = {\n  longitude: -77.0369,\n  latitude: 38.9072,\n  zoom: 4,\n  minZoom: 1,\n  maxZoom: 22,\n  pitch: 0,\n  bearing: 0,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,MAAa,qBAAqB;CAChC,WAAW;CACX,UAAU;CACV,MAAM;CACN,SAAS;CACT,SAAS;CACT,OAAO;CACP,SAAS;CACV"}

package/dist/shared/create-map-store.d.ts

@@ -0,0 +1,202 @@
+/*
+ * 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 { UniqueId } from "@accelint/core";
+
+//#region src/shared/create-map-store.d.ts
+/**
+ * Create a new Map with an entry added or updated (immutable).
+ *
+ * @example
+ * ```ts
+ * const newMap = mapSet(state.cursorOwners, 'draw-layer', 'crosshair');
+ * set({ cursorOwners: newMap });
+ * ```
+ */
+declare function mapSet<K, V>(map: Map<K, V>, key: K, value: V): Map<K, V>;
+/**
+ * Create a new Map with an entry removed (immutable).
+ *
+ * @example
+ * ```ts
+ * const newMap = mapDelete(state.cursorOwners, 'draw-layer');
+ * set({ cursorOwners: newMap });
+ * ```
+ */
+declare function mapDelete<K, V>(map: Map<K, V>, key: K): Map<K, V>;
+/**
+ * Create a new empty Map (immutable replacement for Map.clear()).
+ *
+ * @example
+ * ```ts
+ * set({ pendingRequests: mapClear<string, PendingRequest>() });
+ * ```
+ */
+declare function mapClear<K, V>(): Map<K, V>;
+/**
+ * Helper methods passed to action creators and bus setup functions.
+ *
+ * This type is exported for consumers building custom store extensions or
+ * helper functions that need to interact with store state.
+ *
+ * @example
+ * ```ts
+ * import type { StoreHelpers } from '@accelint/map-toolkit/shared';
+ *
+ * function createCustomAction<T>(helpers: StoreHelpers<T>) {
+ *   return () => {
+ *     const current = helpers.get();
+ *     helpers.set({ ...current, modified: true });
+ *   };
+ * }
+ * ```
+ */
+type StoreHelpers<TState> = {
+  /** Get current state */
+  get: () => TState;
+  /** Update state (partial merge) and notify subscribers */
+  set: (updates: Partial<TState>) => void;
+  /** Replace entire state and notify subscribers */
+  replace: (state: TState) => void;
+  /** Notify subscribers without changing state */
+  notify: () => void;
+};
+/**
+ * Configuration for creating a map store
+ */
+type MapStoreConfig<TState, TActions> = {
+  /** Default state for new instances and SSR */
+  defaultState: TState;
+  /**
+   * Action creators - receives mapId and helpers, returns action methods.
+   * Actions are cached per mapId for referential stability.
+   */
+  actions: (mapId: UniqueId, helpers: StoreHelpers<TState>) => TActions;
+  /**
+   * Optional bus listener setup. Called when first subscriber mounts.
+   * Return cleanup function to unsubscribe.
+   */
+  bus?: (mapId: UniqueId, helpers: StoreHelpers<TState>) => () => void;
+  /**
+   * Optional cleanup when instance is destroyed (last subscriber unmounts).
+   */
+  onCleanup?: (mapId: UniqueId, state: TState) => void;
+};
+/**
+ * The store object returned by createMapStore
+ */
+type MapStore<TState, TActions> = {
+  /**
+   * React hook - the primary way to use the store.
+   * Returns state and actions with proper memoization.
+   */
+  use: (mapId: UniqueId) => {
+    state: TState;
+  } & TActions;
+  /**
+   * React hook with selector for derived state.
+   * Only re-renders when the underlying state changes.
+   *
+   * The selector result is memoized - it only recomputes when the **state reference**
+   * changes, not on every render or when the selector function changes. This means:
+   *
+   * - Selectors that create new objects/arrays are safe without additional memoization
+   * - Changing the selector function does NOT trigger recomputation (by design)
+   * - This prevents infinite re-render loops when using inline arrow functions
+   *
+   * **Important**: The selector function is intentionally NOT tracked as a dependency.
+   * If you need the selector to change dynamically, extract the changing value as a
+   * separate dependency and use it within a stable selector, or use the `use()` hook
+   * with your own `useMemo` for derived state.
+   *
+   * @example
+   * ```ts
+   * // Returns primitive - recomputes when state.count changes
+   * const count = store.useSelector(mapId, (s) => s.count);
+   *
+   * // Returns existing reference - recomputes when state.items ref changes
+   * const items = store.useSelector(mapId, (s) => s.items);
+   *
+   * // Safe: derived object is memoized internally, no infinite loops
+   * const derived = store.useSelector(mapId, (s) => ({ doubled: s.count * 2 }));
+   *
+   * // If you need dynamic selector behavior, use the base hook instead:
+   * const { state } = store.use(mapId);
+   * const filtered = useMemo(() => filterFn(state.items), [state.items, filterFn]);
+   * ```
+   */
+  useSelector: <TSelected>(mapId: UniqueId, selector: (state: TState) => TSelected) => TSelected;
+  /**
+   * Get actions without subscribing to state changes.
+   * Useful for event handlers or effects.
+   */
+  actions: (mapId: UniqueId) => TActions;
+  /**
+   * Get current state (non-reactive, for imperative code).
+   */
+  get: (mapId: UniqueId) => TState;
+  /**
+   * Update state directly (usually prefer actions).
+   */
+  set: (mapId: UniqueId, updates: Partial<TState>) => void;
+  /**
+   * Check if instance exists (has been initialized).
+   */
+  exists: (mapId: UniqueId) => boolean;
+  /**
+   * Clear instance state (for tests or manual cleanup).
+   */
+  clear: (mapId: UniqueId) => void;
+  /**
+   * Low-level access for custom hooks or useSyncExternalStore.
+   */
+  subscribe: (mapId: UniqueId) => (callback: () => void) => () => void;
+  snapshot: (mapId: UniqueId) => () => TState;
+  serverSnapshot: () => TState;
+};
+/**
+ * Creates a store for managing state across multiple map instances.
+ *
+ * @example
+ * ```ts
+ * const cursorStore = createMapStore({
+ *   defaultState: { cursor: 'default', owner: null },
+ *
+ *   actions: (mapId, { get, set }) => ({
+ *     setCursor: (cursor: string, owner: string) => {
+ *       set({ cursor, owner });
+ *     },
+ *     clearCursor: () => {
+ *       set({ cursor: 'default', owner: null });
+ *     },
+ *   }),
+ *
+ *   bus: (mapId, { set }) => {
+ *     return cursorBus.on(CursorEvents.change, (e) => {
+ *       if (e.payload.id === mapId) {
+ *         set({ cursor: e.payload.cursor });
+ *       }
+ *     });
+ *   },
+ * });
+ *
+ * // In component:
+ * function CursorDisplay({ mapId }) {
+ *   const { state, setCursor } = cursorStore.use(mapId);
+ *   return <div style={{ cursor: state.cursor }} />;
+ * }
+ * ```
+ */
+declare function createMapStore<TState, TActions>(config: MapStoreConfig<TState, TActions>): MapStore<TState, TActions>;
+//#endregion
+export { MapStore, MapStoreConfig, StoreHelpers, createMapStore, mapClear, mapDelete, mapSet };
+//# sourceMappingURL=create-map-store.d.ts.map

package/dist/shared/create-map-store.js

@@ -0,0 +1,223 @@
+/*
+ * 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 { useRef, useSyncExternalStore } from "react";
+
+//#region src/shared/create-map-store.ts
+/**
+* Create a new Map with an entry added or updated (immutable).
+*
+* @example
+* ```ts
+* const newMap = mapSet(state.cursorOwners, 'draw-layer', 'crosshair');
+* set({ cursorOwners: newMap });
+* ```
+*/
+function mapSet(map, key, value) {
+	const newMap = new Map(map);
+	newMap.set(key, value);
+	return newMap;
+}
+/**
+* Create a new Map with an entry removed (immutable).
+*
+* @example
+* ```ts
+* const newMap = mapDelete(state.cursorOwners, 'draw-layer');
+* set({ cursorOwners: newMap });
+* ```
+*/
+function mapDelete(map, key) {
+	const newMap = new Map(map);
+	newMap.delete(key);
+	return newMap;
+}
+/**
+* Create a new empty Map (immutable replacement for Map.clear()).
+*
+* @example
+* ```ts
+* set({ pendingRequests: mapClear<string, PendingRequest>() });
+* ```
+*/
+function mapClear() {
+	return /* @__PURE__ */ new Map();
+}
+/**
+* Creates a store for managing state across multiple map instances.
+*
+* @example
+* ```ts
+* const cursorStore = createMapStore({
+*   defaultState: { cursor: 'default', owner: null },
+*
+*   actions: (mapId, { get, set }) => ({
+*     setCursor: (cursor: string, owner: string) => {
+*       set({ cursor, owner });
+*     },
+*     clearCursor: () => {
+*       set({ cursor: 'default', owner: null });
+*     },
+*   }),
+*
+*   bus: (mapId, { set }) => {
+*     return cursorBus.on(CursorEvents.change, (e) => {
+*       if (e.payload.id === mapId) {
+*         set({ cursor: e.payload.cursor });
+*       }
+*     });
+*   },
+* });
+*
+* // In component:
+* function CursorDisplay({ mapId }) {
+*   const { state, setCursor } = cursorStore.use(mapId);
+*   return <div style={{ cursor: state.cursor }} />;
+* }
+* ```
+*/
+function createMapStore(config) {
+	const { defaultState, actions: createActions, bus, onCleanup } = config;
+	const instances = /* @__PURE__ */ new Map();
+	const subscriptionCache = /* @__PURE__ */ new Map();
+	const snapshotCache = /* @__PURE__ */ new Map();
+	function getInstance(mapId) {
+		let instance = instances.get(mapId);
+		if (!instance) {
+			instance = {
+				state: { ...defaultState },
+				subscribers: /* @__PURE__ */ new Set()
+			};
+			instances.set(mapId, instance);
+		}
+		return instance;
+	}
+	function notify(mapId) {
+		const instance = instances.get(mapId);
+		if (instance) for (const callback of instance.subscribers) callback();
+	}
+	function getHelpers(mapId) {
+		return {
+			get: () => getInstance(mapId).state,
+			set: (updates) => {
+				const instance = getInstance(mapId);
+				instance.state = {
+					...instance.state,
+					...updates
+				};
+				notify(mapId);
+			},
+			replace: (state) => {
+				const instance = getInstance(mapId);
+				instance.state = state;
+				notify(mapId);
+			},
+			notify: () => notify(mapId)
+		};
+	}
+	function getActions(mapId) {
+		const instance = getInstance(mapId);
+		if (!instance.actions) instance.actions = createActions(mapId, getHelpers(mapId));
+		return instance.actions;
+	}
+	/**
+	* Clean up instance when last subscriber unmounts
+	*/
+	function cleanupInstance(mapId, instance) {
+		if (onCleanup) onCleanup(mapId, instance.state);
+		if (instance.busCleanup) instance.busCleanup();
+		instances.delete(mapId);
+		subscriptionCache.delete(mapId);
+		snapshotCache.delete(mapId);
+	}
+	function subscribe(mapId) {
+		let cached = subscriptionCache.get(mapId);
+		if (!cached) {
+			cached = (callback) => {
+				const instance = getInstance(mapId);
+				if (instance.subscribers.size === 0 && bus) instance.busCleanup = bus(mapId, getHelpers(mapId));
+				instance.subscribers.add(callback);
+				return () => {
+					instance.subscribers.delete(callback);
+					if (instance.subscribers.size === 0) cleanupInstance(mapId, instance);
+				};
+			};
+			subscriptionCache.set(mapId, cached);
+		}
+		return cached;
+	}
+	function snapshot(mapId) {
+		let cached = snapshotCache.get(mapId);
+		if (!cached) {
+			cached = () => {
+				return getInstance(mapId).state;
+			};
+			snapshotCache.set(mapId, cached);
+		}
+		return cached;
+	}
+	function serverSnapshot() {
+		return defaultState;
+	}
+	/**
+	* Main hook - returns state and actions
+	*/
+	function use(mapId) {
+		return {
+			state: useSyncExternalStore(subscribe(mapId), snapshot(mapId), serverSnapshot),
+			...getActions(mapId)
+		};
+	}
+	/**
+	* Selector hook - only re-renders when selected value changes.
+	*
+	* Note: The selector function is intentionally NOT tracked as a dependency.
+	* This prevents infinite re-render loops when using inline arrow functions.
+	* If you need dynamic selector behavior, use the `use()` hook with `useMemo`.
+	*/
+	function useSelector(mapId, selector) {
+		const cache = useRef(null);
+		const state = useSyncExternalStore(subscribe(mapId), snapshot(mapId), serverSnapshot);
+		if (cache.current === null || cache.current.state !== state) cache.current = {
+			state,
+			selected: selector(state)
+		};
+		return cache.current.selected;
+	}
+	return {
+		use,
+		useSelector,
+		actions: getActions,
+		get: (mapId) => getInstance(mapId).state,
+		set: (mapId, updates) => {
+			const instance = getInstance(mapId);
+			instance.state = {
+				...instance.state,
+				...updates
+			};
+			notify(mapId);
+		},
+		exists: (mapId) => instances.has(mapId),
+		clear: (mapId) => {
+			const instance = instances.get(mapId);
+			if (instance) cleanupInstance(mapId, instance);
+		},
+		subscribe,
+		snapshot,
+		serverSnapshot
+	};
+}
+
+//#endregion
+export { createMapStore, mapClear, mapDelete, mapSet };
+//# sourceMappingURL=create-map-store.js.map

package/dist/shared/create-map-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-map-store.js","names":[],"sources":["../../src/shared/create-map-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\nimport { useRef, useSyncExternalStore } from 'react';\nimport type { UniqueId } from '@accelint/core';\n\n// =============================================================================\n// Immutable Map Helpers\n// =============================================================================\n\n/**\n * Create a new Map with an entry added or updated (immutable).\n *\n * @example\n * ```ts\n * const newMap = mapSet(state.cursorOwners, 'draw-layer', 'crosshair');\n * set({ cursorOwners: newMap });\n * ```\n */\nexport function mapSet<K, V>(map: Map<K, V>, key: K, value: V): Map<K, V> {\n  const newMap = new Map(map);\n  newMap.set(key, value);\n  return newMap;\n}\n\n/**\n * Create a new Map with an entry removed (immutable).\n *\n * @example\n * ```ts\n * const newMap = mapDelete(state.cursorOwners, 'draw-layer');\n * set({ cursorOwners: newMap });\n * ```\n */\nexport function mapDelete<K, V>(map: Map<K, V>, key: K): Map<K, V> {\n  const newMap = new Map(map);\n  newMap.delete(key);\n  return newMap;\n}\n\n/**\n * Create a new empty Map (immutable replacement for Map.clear()).\n *\n * @example\n * ```ts\n * set({ pendingRequests: mapClear<string, PendingRequest>() });\n * ```\n */\nexport function mapClear<K, V>(): Map<K, V> {\n  return new Map<K, V>();\n}\n\n/**\n * Helper methods passed to action creators and bus setup functions.\n *\n * This type is exported for consumers building custom store extensions or\n * helper functions that need to interact with store state.\n *\n * @example\n * ```ts\n * import type { StoreHelpers } from '@accelint/map-toolkit/shared';\n *\n * function createCustomAction<T>(helpers: StoreHelpers<T>) {\n *   return () => {\n *     const current = helpers.get();\n *     helpers.set({ ...current, modified: true });\n *   };\n * }\n * ```\n */\nexport type StoreHelpers<TState> = {\n  /** Get current state */\n  get: () => TState;\n  /** Update state (partial merge) and notify subscribers */\n  set: (updates: Partial<TState>) => void;\n  /** Replace entire state and notify subscribers */\n  replace: (state: TState) => void;\n  /** Notify subscribers without changing state */\n  notify: () => void;\n};\n\n/**\n * Configuration for creating a map store\n */\nexport type MapStoreConfig<TState, TActions> = {\n  /** Default state for new instances and SSR */\n  defaultState: TState;\n\n  /**\n   * Action creators - receives mapId and helpers, returns action methods.\n   * Actions are cached per mapId for referential stability.\n   */\n  actions: (mapId: UniqueId, helpers: StoreHelpers<TState>) => TActions;\n\n  /**\n   * Optional bus listener setup. Called when first subscriber mounts.\n   * Return cleanup function to unsubscribe.\n   */\n  bus?: (mapId: UniqueId, helpers: StoreHelpers<TState>) => () => void;\n\n  /**\n   * Optional cleanup when instance is destroyed (last subscriber unmounts).\n   */\n  onCleanup?: (mapId: UniqueId, state: TState) => void;\n};\n\n/**\n * Instance data for a single map\n */\ntype Instance<TState, TActions> = {\n  state: TState;\n  actions?: TActions;\n  subscribers: Set<() => void>;\n  busCleanup?: () => void;\n};\n\n/**\n * The store object returned by createMapStore\n */\nexport type MapStore<TState, TActions> = {\n  /**\n   * React hook - the primary way to use the store.\n   * Returns state and actions with proper memoization.\n   */\n  use: (mapId: UniqueId) => { state: TState } & TActions;\n\n  /**\n   * React hook with selector for derived state.\n   * Only re-renders when the underlying state changes.\n   *\n   * The selector result is memoized - it only recomputes when the **state reference**\n   * changes, not on every render or when the selector function changes. This means:\n   *\n   * - Selectors that create new objects/arrays are safe without additional memoization\n   * - Changing the selector function does NOT trigger recomputation (by design)\n   * - This prevents infinite re-render loops when using inline arrow functions\n   *\n   * **Important**: The selector function is intentionally NOT tracked as a dependency.\n   * If you need the selector to change dynamically, extract the changing value as a\n   * separate dependency and use it within a stable selector, or use the `use()` hook\n   * with your own `useMemo` for derived state.\n   *\n   * @example\n   * ```ts\n   * // Returns primitive - recomputes when state.count changes\n   * const count = store.useSelector(mapId, (s) => s.count);\n   *\n   * // Returns existing reference - recomputes when state.items ref changes\n   * const items = store.useSelector(mapId, (s) => s.items);\n   *\n   * // Safe: derived object is memoized internally, no infinite loops\n   * const derived = store.useSelector(mapId, (s) => ({ doubled: s.count * 2 }));\n   *\n   * // If you need dynamic selector behavior, use the base hook instead:\n   * const { state } = store.use(mapId);\n   * const filtered = useMemo(() => filterFn(state.items), [state.items, filterFn]);\n   * ```\n   */\n  useSelector: <TSelected>(\n    mapId: UniqueId,\n    selector: (state: TState) => TSelected,\n  ) => TSelected;\n\n  /**\n   * Get actions without subscribing to state changes.\n   * Useful for event handlers or effects.\n   */\n  actions: (mapId: UniqueId) => TActions;\n\n  /**\n   * Get current state (non-reactive, for imperative code).\n   */\n  get: (mapId: UniqueId) => TState;\n\n  /**\n   * Update state directly (usually prefer actions).\n   */\n  set: (mapId: UniqueId, updates: Partial<TState>) => void;\n\n  /**\n   * Check if instance exists (has been initialized).\n   */\n  exists: (mapId: UniqueId) => boolean;\n\n  /**\n   * Clear instance state (for tests or manual cleanup).\n   */\n  clear: (mapId: UniqueId) => void;\n\n  /**\n   * Low-level access for custom hooks or useSyncExternalStore.\n   */\n  subscribe: (mapId: UniqueId) => (callback: () => void) => () => void;\n  snapshot: (mapId: UniqueId) => () => TState;\n  serverSnapshot: () => TState;\n};\n\n/**\n * Creates a store for managing state across multiple map instances.\n *\n * @example\n * ```ts\n * const cursorStore = createMapStore({\n *   defaultState: { cursor: 'default', owner: null },\n *\n *   actions: (mapId, { get, set }) => ({\n *     setCursor: (cursor: string, owner: string) => {\n *       set({ cursor, owner });\n *     },\n *     clearCursor: () => {\n *       set({ cursor: 'default', owner: null });\n *     },\n *   }),\n *\n *   bus: (mapId, { set }) => {\n *     return cursorBus.on(CursorEvents.change, (e) => {\n *       if (e.payload.id === mapId) {\n *         set({ cursor: e.payload.cursor });\n *       }\n *     });\n *   },\n * });\n *\n * // In component:\n * function CursorDisplay({ mapId }) {\n *   const { state, setCursor } = cursorStore.use(mapId);\n *   return <div style={{ cursor: state.cursor }} />;\n * }\n * ```\n */\nexport function createMapStore<TState, TActions>(\n  config: MapStoreConfig<TState, TActions>,\n): MapStore<TState, TActions> {\n  const { defaultState, actions: createActions, bus, onCleanup } = config;\n\n  const instances = new Map<UniqueId, Instance<TState, TActions>>();\n\n  // Cached functions for referential stability\n  const subscriptionCache = new Map<\n    UniqueId,\n    (callback: () => void) => () => void\n  >();\n  const snapshotCache = new Map<UniqueId, () => TState>();\n\n  function getInstance(mapId: UniqueId): Instance<TState, TActions> {\n    let instance = instances.get(mapId);\n    if (!instance) {\n      instance = {\n        state: { ...defaultState },\n        subscribers: new Set(),\n      };\n      instances.set(mapId, instance);\n    }\n    return instance;\n  }\n\n  function notify(mapId: UniqueId): void {\n    const instance = instances.get(mapId);\n    if (instance) {\n      for (const callback of instance.subscribers) {\n        callback();\n      }\n    }\n  }\n\n  function getHelpers(mapId: UniqueId): StoreHelpers<TState> {\n    return {\n      get: () => getInstance(mapId).state,\n      set: (updates) => {\n        const instance = getInstance(mapId);\n        instance.state = { ...instance.state, ...updates };\n        notify(mapId);\n      },\n      replace: (state) => {\n        const instance = getInstance(mapId);\n        instance.state = state;\n        notify(mapId);\n      },\n      notify: () => notify(mapId),\n    };\n  }\n\n  function getActions(mapId: UniqueId): TActions {\n    const instance = getInstance(mapId);\n    if (!instance.actions) {\n      instance.actions = createActions(mapId, getHelpers(mapId));\n    }\n    return instance.actions;\n  }\n\n  /**\n   * Clean up instance when last subscriber unmounts\n   */\n  function cleanupInstance(\n    mapId: UniqueId,\n    instance: Instance<TState, TActions>,\n  ): void {\n    if (onCleanup) {\n      onCleanup(mapId, instance.state);\n    }\n    if (instance.busCleanup) {\n      instance.busCleanup();\n    }\n    instances.delete(mapId);\n    subscriptionCache.delete(mapId);\n    snapshotCache.delete(mapId);\n  }\n\n  function subscribe(mapId: UniqueId): (callback: () => void) => () => void {\n    let cached = subscriptionCache.get(mapId);\n    if (!cached) {\n      cached = (callback: () => void) => {\n        const instance = getInstance(mapId);\n\n        // Setup bus on first subscriber\n        if (instance.subscribers.size === 0 && bus) {\n          instance.busCleanup = bus(mapId, getHelpers(mapId));\n        }\n\n        instance.subscribers.add(callback);\n\n        return () => {\n          instance.subscribers.delete(callback);\n\n          // Cleanup when last subscriber unmounts\n          if (instance.subscribers.size === 0) {\n            cleanupInstance(mapId, instance);\n          }\n        };\n      };\n      subscriptionCache.set(mapId, cached);\n    }\n    return cached;\n  }\n\n  function snapshot(mapId: UniqueId): () => TState {\n    let cached = snapshotCache.get(mapId);\n    if (!cached) {\n      cached = () => {\n        // State is already a new object reference when updated via set()\n        // which creates { ...instance.state, ...updates }\n        return getInstance(mapId).state;\n      };\n      snapshotCache.set(mapId, cached);\n    }\n    return cached;\n  }\n\n  function serverSnapshot(): TState {\n    return defaultState;\n  }\n\n  /**\n   * Main hook - returns state and actions\n   */\n  function use(mapId: UniqueId): { state: TState } & TActions {\n    const state = useSyncExternalStore(\n      subscribe(mapId),\n      snapshot(mapId),\n      serverSnapshot,\n    );\n\n    const actions = getActions(mapId);\n\n    // Return merged object with state wrapper for clarity\n    return { state, ...actions };\n  }\n\n  /**\n   * Selector hook - only re-renders when selected value changes.\n   *\n   * Note: The selector function is intentionally NOT tracked as a dependency.\n   * This prevents infinite re-render loops when using inline arrow functions.\n   * If you need dynamic selector behavior, use the `use()` hook with `useMemo`.\n   */\n  function useSelector<TSelected>(\n    mapId: UniqueId,\n    selector: (state: TState) => TSelected,\n  ): TSelected {\n    // Cache the previous state and selected value to avoid unnecessary re-computation.\n    // We intentionally do NOT track selector changes - only state changes trigger\n    // recomputation. This prevents infinite loops with inline selectors.\n    const cache = useRef<{ state: TState; selected: TSelected } | null>(null);\n\n    const state = useSyncExternalStore(\n      subscribe(mapId),\n      snapshot(mapId),\n      serverSnapshot,\n    );\n\n    // Only recompute if state reference changed (selector changes are ignored)\n    if (cache.current === null || cache.current.state !== state) {\n      cache.current = {\n        state,\n        selected: selector(state),\n      };\n    }\n\n    return cache.current.selected;\n  }\n\n  return {\n    use,\n    useSelector,\n    actions: getActions,\n    get: (mapId) => getInstance(mapId).state,\n    set: (mapId, updates) => {\n      const instance = getInstance(mapId);\n      instance.state = { ...instance.state, ...updates };\n      notify(mapId);\n    },\n    exists: (mapId) => instances.has(mapId),\n    clear: (mapId) => {\n      const instance = instances.get(mapId);\n      if (instance) {\n        cleanupInstance(mapId, instance);\n      }\n    },\n    subscribe,\n    snapshot,\n    serverSnapshot,\n  };\n}\n"],"mappings":"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"}

package/dist/shared/units.d.ts

@@ -0,0 +1,39 @@
+//#region src/shared/units.d.ts
+/**
+ * Map of Turf.js unit names to display abbreviations.
+ * These are the practical units users would select for map measurements.
+ */
+declare const DISTANCE_UNIT_ABBREVIATIONS: {
+  readonly kilometers: "km";
+  readonly meters: "m";
+  readonly nauticalmiles: "nm";
+  readonly miles: "mi";
+  readonly feet: "ft";
+};
+/**
+ * Turf.js unit name (e.g., 'kilometers', 'nauticalmiles').
+ */
+type DistanceUnit = keyof typeof DISTANCE_UNIT_ABBREVIATIONS;
+/**
+ * Display abbreviation (e.g., 'km', 'nm').
+ */
+type DistanceUnitAbbreviation = (typeof DISTANCE_UNIT_ABBREVIATIONS)[DistanceUnit];
+/**
+ * Default distance units for geographic measurements.
+ */
+declare const DEFAULT_DISTANCE_UNITS: DistanceUnit;
+/**
+ * Get the full Turf.js unit name from an abbreviation.
+ * @param abbrev - The abbreviation (e.g., 'km', 'nm')
+ * @returns The full unit name (e.g., 'kilometers', 'nauticalmiles') or undefined
+ */
+declare function getDistanceUnitFromAbbreviation(abbrev: string): DistanceUnit | undefined;
+/**
+ * Get the abbreviation for a Turf.js unit name.
+ * @param unit - The full unit name (e.g., 'kilometers')
+ * @returns The abbreviation (e.g., 'km') or the input if not found
+ */
+declare function getDistanceUnitAbbreviation(unit: string): string;
+//#endregion
+export { DEFAULT_DISTANCE_UNITS, DISTANCE_UNIT_ABBREVIATIONS, DistanceUnit, DistanceUnitAbbreviation, getDistanceUnitAbbreviation, getDistanceUnitFromAbbreviation };
+//# sourceMappingURL=units.d.ts.map

package/dist/shared/units.js

@@ -0,0 +1,49 @@
+/*
+ * 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/shared/units.ts
+/**
+* Map of Turf.js unit names to display abbreviations.
+* These are the practical units users would select for map measurements.
+*/
+const DISTANCE_UNIT_ABBREVIATIONS = {
+	kilometers: "km",
+	meters: "m",
+	nauticalmiles: "nm",
+	miles: "mi",
+	feet: "ft"
+};
+/**
+* Default distance units for geographic measurements.
+*/
+const DEFAULT_DISTANCE_UNITS = "kilometers";
+/**
+* Get the full Turf.js unit name from an abbreviation.
+* @param abbrev - The abbreviation (e.g., 'km', 'nm')
+* @returns The full unit name (e.g., 'kilometers', 'nauticalmiles') or undefined
+*/
+function getDistanceUnitFromAbbreviation(abbrev) {
+	return Object.entries(DISTANCE_UNIT_ABBREVIATIONS).find(([, a]) => a === abbrev)?.[0];
+}
+/**
+* Get the abbreviation for a Turf.js unit name.
+* @param unit - The full unit name (e.g., 'kilometers')
+* @returns The abbreviation (e.g., 'km') or the input if not found
+*/
+function getDistanceUnitAbbreviation(unit) {
+	return DISTANCE_UNIT_ABBREVIATIONS[unit] ?? unit;
+}
+
+//#endregion
+export { DEFAULT_DISTANCE_UNITS, DISTANCE_UNIT_ABBREVIATIONS, getDistanceUnitAbbreviation, getDistanceUnitFromAbbreviation };
+//# sourceMappingURL=units.js.map

package/dist/shared/units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","names":["DEFAULT_DISTANCE_UNITS: DistanceUnit"],"sources":["../../src/shared/units.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 * Map of Turf.js unit names to display abbreviations.\n * These are the practical units users would select for map measurements.\n */\nexport const DISTANCE_UNIT_ABBREVIATIONS = {\n  kilometers: 'km',\n  meters: 'm',\n  nauticalmiles: 'nm',\n  miles: 'mi',\n  feet: 'ft',\n} as const;\n\n/**\n * Turf.js unit name (e.g., 'kilometers', 'nauticalmiles').\n */\nexport type DistanceUnit = keyof typeof DISTANCE_UNIT_ABBREVIATIONS;\n\n/**\n * Display abbreviation (e.g., 'km', 'nm').\n */\nexport type DistanceUnitAbbreviation =\n  (typeof DISTANCE_UNIT_ABBREVIATIONS)[DistanceUnit];\n\n/**\n * Default distance units for geographic measurements.\n */\nexport const DEFAULT_DISTANCE_UNITS: DistanceUnit = 'kilometers';\n\n/**\n * Get the full Turf.js unit name from an abbreviation.\n * @param abbrev - The abbreviation (e.g., 'km', 'nm')\n * @returns The full unit name (e.g., 'kilometers', 'nauticalmiles') or undefined\n */\nexport function getDistanceUnitFromAbbreviation(\n  abbrev: string,\n): DistanceUnit | undefined {\n  const entry = Object.entries(DISTANCE_UNIT_ABBREVIATIONS).find(\n    ([, a]) => a === abbrev,\n  );\n  return entry?.[0] as DistanceUnit | undefined;\n}\n\n/**\n * Get the abbreviation for a Turf.js unit name.\n * @param unit - The full unit name (e.g., 'kilometers')\n * @returns The abbreviation (e.g., 'km') or the input if not found\n */\nexport function getDistanceUnitAbbreviation(unit: string): string {\n  return DISTANCE_UNIT_ABBREVIATIONS[unit as DistanceUnit] ?? unit;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgBA,MAAa,8BAA8B;CACzC,YAAY;CACZ,QAAQ;CACR,eAAe;CACf,OAAO;CACP,MAAM;CACP;;;;AAgBD,MAAaA,yBAAuC;;;;;;AAOpD,SAAgB,gCACd,QAC0B;AAI1B,QAHc,OAAO,QAAQ,4BAA4B,CAAC,MACvD,GAAG,OAAO,MAAM,OAClB,GACc;;;;;;;AAQjB,SAAgB,4BAA4B,MAAsB;AAChE,QAAO,4BAA4B,SAAyB"}

package/dist/viewport/index.d.ts

@@ -10,9 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
-import { UNIT_MAP } from "./constants.js";
-import { UseViewportStateProps, clearViewportState, useViewportState } from "./use-viewport-state.js";
+import { DISTANCE_UNIT_ABBREVIATIONS, DistanceUnit, DistanceUnitAbbreviation, getDistanceUnitFromAbbreviation } from "../shared/units.js";
+import { clearViewportState, useMapViewport, viewportStore } from "./store.js";
 import { GeoCoordinate, GetViewportSizeArgs, SupportedDistanceUnit } from "./types.js";
 import { getViewportSize } from "./utils.js";
 import { ViewportSize, ViewportSizeProps } from "./viewport-size.js";
-export { type GeoCoordinate, type GetViewportSizeArgs, type SupportedDistanceUnit, UNIT_MAP, type UseViewportStateProps, ViewportSize, type ViewportSizeProps, clearViewportState, getViewportSize, useViewportState };
+export { DISTANCE_UNIT_ABBREVIATIONS, type DistanceUnit, type DistanceUnitAbbreviation, type GeoCoordinate, type GetViewportSizeArgs, type SupportedDistanceUnit, ViewportSize, type ViewportSizeProps, clearViewportState, getDistanceUnitFromAbbreviation, getViewportSize, useMapViewport, viewportStore };

package/dist/viewport/index.js

@@ -11,9 +11,9 @@
  */
 
 
-import { UNIT_MAP } from "./constants.js";
-import { clearViewportState, useViewportState } from "./use-viewport-state.js";
+import { DISTANCE_UNIT_ABBREVIATIONS, getDistanceUnitFromAbbreviation } from "../shared/units.js";
+import { clearViewportState, useMapViewport, viewportStore } from "./store.js";
 import { getViewportSize } from "./utils.js";
 import { ViewportSize } from "./viewport-size.js";
 
-export { UNIT_MAP, ViewportSize, clearViewportState, getViewportSize, useViewportState };
+export { DISTANCE_UNIT_ABBREVIATIONS, ViewportSize, clearViewportState, getDistanceUnitFromAbbreviation, getViewportSize, useMapViewport, viewportStore };