@accelint/map-toolkit 0.4.1 → 0.6.0

package/dist/deckgl/shapes/display-shape-layer/store.d.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { ShapeId } from "../shared/types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/deckgl/shapes/display-shape-layer/store.d.ts
+/**
+ * Creates or retrieves a cached subscription function for a given mapId.
+ * Uses a fan-out pattern: 1 bus listener -> N React subscribers.
+ * Automatically cleans up selection state when the last subscriber unsubscribes.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A subscription function for useSyncExternalStore
+ */
+declare function getOrCreateSubscription(mapId: UniqueId): (onStoreChange: () => void) => () => void;
+/**
+ * Creates or retrieves a cached snapshot function for a given mapId.
+ * The selection ID returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A snapshot function for useSyncExternalStore
+ */
+declare function getOrCreateSnapshot(mapId: UniqueId): () => ShapeId | undefined;
+/**
+ * Creates or retrieves a cached server snapshot function for a given mapId.
+ * Server snapshots always return undefined since selection state is client-only.
+ * Required for SSR/RSC compatibility with useSyncExternalStore.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A server snapshot function for useSyncExternalStore
+ */
+declare function getOrCreateServerSnapshot(mapId: UniqueId): () => ShapeId | undefined;
+/**
+ * Creates or retrieves a cached setSelectedId function for a given mapId.
+ * This maintains referential stability for the function reference.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A setSelectedId function for this instance
+ */
+declare function getOrCreateSetSelectedId(mapId: UniqueId): (id: ShapeId | undefined) => void;
+/**
+ * Creates or retrieves a cached clearSelection function for a given mapId.
+ * This maintains referential stability for the function reference.
+ *
+ * Note: This always emits a deselected event, even if nothing is currently selected.
+ * This matches the original behavior and allows consumers to use clearSelection
+ * as a "force deselect" without needing to check selection state first.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A clearSelection function for this instance
+ */
+declare function getOrCreateClearSelection(mapId: UniqueId): () => void;
+/**
+ * Get the current selected shape ID for a given map instance (direct access, not reactive).
+ * @internal - For internal map-toolkit use only
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns The currently selected shape ID, or undefined
+ */
+declare function getSelectedShapeId(mapId: UniqueId): ShapeId | undefined;
+/**
+ * Manually clear all selection state for a specific mapId.
+ * 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 mapId - The unique identifier for the map instance to clear
+ *
+ * @example
+ * ```tsx
+ * // Manual cleanup (rarely needed)
+ * clearSelectionState('my-map-instance');
+ * ```
+ */
+declare function clearSelectionState(mapId: UniqueId): void;
+//#endregion
+export { clearSelectionState, getOrCreateClearSelection, getOrCreateServerSnapshot, getOrCreateSetSelectedId, getOrCreateSnapshot, getOrCreateSubscription, getSelectedShapeId };
+//# sourceMappingURL=store.d.ts.map

package/dist/deckgl/shapes/display-shape-layer/store.js

@@ -0,0 +1,316 @@
+/*
+ * 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 "../../base-map/events.js";
+import { ShapeEvents } from "../shared/events.js";
+import { Broadcast } from "@accelint/bus";
+
+//#region src/deckgl/shapes/display-shape-layer/store.ts
+/**
+* Shape Selection Store
+*
+* This module provides a store pattern for managing shape selection state,
+* designed to work with React's `useSyncExternalStore` hook.
+*
+* ## Architecture
+*
+* The store uses a fan-out pattern similar to `map-cursor/store.ts` and `map-mode/store.ts`:
+* - **1 bus listener per mapId** - Regardless of how many React components subscribe
+* - **N React subscribers** - Each component gets notified via `useSyncExternalStore`
+* - **Automatic cleanup** - Bus listeners are removed when the last subscriber unmounts
+*
+* ## Why This Pattern?
+*
+* Without this pattern, using `useOn` directly in each React component would
+* create N bus listeners for N components subscribing to the same events.
+* The fan-out pattern ensures exactly 1 bus listener per mapId, regardless
+* of how many React components need the state. This also provides proper
+* cleanup semantics that prevent listener accumulation during HMR.
+*
+* ## Usage
+*
+* This module is internal to `useShapeSelection`. Use the hook instead:
+*
+* ```tsx
+* import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';
+*
+* const { selectedId, setSelectedId, clearSelection } = useShapeSelection(mapId);
+* ```
+*
+* @module
+*/
+/**
+* Typed event bus instances for shape and map events
+*/
+const shapeBus = Broadcast.getInstance();
+const mapBus = Broadcast.getInstance();
+/**
+* Store for shape selection state keyed by mapId
+*/
+const selectionStore = /* @__PURE__ */ new Map();
+/**
+* Track React component subscribers per mapId (for fan-out notifications).
+* Each Set contains onStoreChange callbacks from useSyncExternalStore.
+*/
+const componentSubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of bus unsubscribe functions (1 per mapId).
+* This ensures we only have one bus listener per map instance, regardless of
+* how many React components subscribe to it.
+*/
+const busUnsubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of subscription functions per mapId to avoid recreating on every render
+*/
+const subscriptionCache = /* @__PURE__ */ new Map();
+/**
+* Cache of snapshot functions per mapId to maintain referential stability
+*/
+const snapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of server snapshot functions per mapId to maintain referential stability.
+* Server snapshots always return undefined since selection state is client-only.
+*/
+const serverSnapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of setSelectedId functions per mapId to maintain referential stability
+*/
+const setSelectedIdCache = /* @__PURE__ */ new Map();
+/**
+* Cache of clearSelection functions per mapId to maintain referential stability
+*/
+const clearSelectionCache = /* @__PURE__ */ new Map();
+/**
+* All state caches that need cleanup when an instance is removed
+*/
+const stateCaches = [
+	selectionStore,
+	componentSubscribers,
+	subscriptionCache,
+	snapshotCache,
+	serverSnapshotCache,
+	setSelectedIdCache,
+	clearSelectionCache
+];
+/**
+* Clear all cached state for a given mapId
+*/
+function clearAllCaches(mapId) {
+	for (const cache of stateCaches) cache.delete(mapId);
+}
+/**
+* Get or create selection state for a given mapId
+*/
+function getOrCreateState(mapId) {
+	if (!selectionStore.has(mapId)) selectionStore.set(mapId, { selectedId: void 0 });
+	return selectionStore.get(mapId);
+}
+/**
+* Get current selection snapshot for a given map instance (for useSyncExternalStore)
+*/
+function getSnapshot(mapId) {
+	return selectionStore.get(mapId)?.selectedId;
+}
+/**
+* Notify all React subscribers for a given mapId
+*/
+function notifySubscribers(mapId) {
+	const subscribers = componentSubscribers.get(mapId);
+	if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
+}
+/**
+* Ensures a single bus listener exists for the given mapId.
+* All React subscribers will be notified via fan-out when the bus events fire.
+* This prevents creating N bus listeners for N React components.
+*
+* @param mapId - The unique identifier for the map instance
+*/
+function ensureBusListener(mapId) {
+	if (busUnsubscribers.has(mapId)) return;
+	const state = getOrCreateState(mapId);
+	const unsubSelected = shapeBus.on(ShapeEvents.selected, (event) => {
+		if (event.payload.mapId !== mapId) return;
+		const previousId = state.selectedId;
+		state.selectedId = event.payload.shapeId;
+		if (previousId !== state.selectedId) notifySubscribers(mapId);
+	});
+	const unsubDeselected = shapeBus.on(ShapeEvents.deselected, (event) => {
+		if (event.payload.mapId !== mapId) return;
+		const previousId = state.selectedId;
+		state.selectedId = void 0;
+		if (previousId !== state.selectedId) notifySubscribers(mapId);
+	});
+	const unsubClick = mapBus.on(MapEvents.click, (event) => {
+		if (state.selectedId && event.payload.id === mapId && event.payload.info.index === -1) shapeBus.emit(ShapeEvents.deselected, { mapId });
+	});
+	busUnsubscribers.set(mapId, () => {
+		unsubSelected();
+		unsubDeselected();
+		unsubClick();
+	});
+}
+/**
+* Cleans up the bus listener if no React subscribers remain.
+*
+* @param mapId - The unique identifier for the map instance
+*/
+function cleanupBusListenerIfNeeded(mapId) {
+	const subscribers = componentSubscribers.get(mapId);
+	if (!subscribers || subscribers.size === 0) {
+		const unsub = busUnsubscribers.get(mapId);
+		if (unsub) {
+			unsub();
+			busUnsubscribers.delete(mapId);
+		}
+		clearAllCaches(mapId);
+	}
+}
+/**
+* Creates or retrieves a cached subscription function for a given mapId.
+* Uses a fan-out pattern: 1 bus listener -> N React subscribers.
+* Automatically cleans up selection state when the last subscriber unsubscribes.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A subscription function for useSyncExternalStore
+*/
+function getOrCreateSubscription(mapId) {
+	let subscription = subscriptionCache.get(mapId);
+	if (!subscription) {
+		subscription = (onStoreChange) => {
+			getOrCreateState(mapId);
+			ensureBusListener(mapId);
+			let subscriberSet = componentSubscribers.get(mapId);
+			if (!subscriberSet) {
+				subscriberSet = /* @__PURE__ */ new Set();
+				componentSubscribers.set(mapId, subscriberSet);
+			}
+			subscriberSet.add(onStoreChange);
+			return () => {
+				const currentSubscriberSet = componentSubscribers.get(mapId);
+				if (currentSubscriberSet) currentSubscriberSet.delete(onStoreChange);
+				cleanupBusListenerIfNeeded(mapId);
+			};
+		};
+		subscriptionCache.set(mapId, subscription);
+	}
+	return subscription;
+}
+/**
+* Creates or retrieves a cached snapshot function for a given mapId.
+* The selection ID returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A snapshot function for useSyncExternalStore
+*/
+function getOrCreateSnapshot(mapId) {
+	let snapshot = snapshotCache.get(mapId);
+	if (!snapshot) {
+		snapshot = () => getSnapshot(mapId);
+		snapshotCache.set(mapId, snapshot);
+	}
+	return snapshot;
+}
+/**
+* Creates or retrieves a cached server snapshot function for a given mapId.
+* Server snapshots always return undefined since selection state is client-only.
+* Required for SSR/RSC compatibility with useSyncExternalStore.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A server snapshot function for useSyncExternalStore
+*/
+function getOrCreateServerSnapshot(mapId) {
+	let serverSnapshot = serverSnapshotCache.get(mapId);
+	if (!serverSnapshot) {
+		serverSnapshot = () => void 0;
+		serverSnapshotCache.set(mapId, serverSnapshot);
+	}
+	return serverSnapshot;
+}
+/**
+* Creates or retrieves a cached setSelectedId function for a given mapId.
+* This maintains referential stability for the function reference.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A setSelectedId function for this instance
+*/
+function getOrCreateSetSelectedId(mapId) {
+	let setSelectedId = setSelectedIdCache.get(mapId);
+	if (!setSelectedId) {
+		setSelectedId = (id) => {
+			const previousId = getOrCreateState(mapId).selectedId;
+			if (id === void 0 && previousId !== void 0) shapeBus.emit(ShapeEvents.deselected, { mapId });
+			else if (id !== void 0 && previousId !== id) shapeBus.emit(ShapeEvents.selected, {
+				shapeId: id,
+				mapId
+			});
+		};
+		setSelectedIdCache.set(mapId, setSelectedId);
+	}
+	return setSelectedId;
+}
+/**
+* Creates or retrieves a cached clearSelection function for a given mapId.
+* This maintains referential stability for the function reference.
+*
+* Note: This always emits a deselected event, even if nothing is currently selected.
+* This matches the original behavior and allows consumers to use clearSelection
+* as a "force deselect" without needing to check selection state first.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A clearSelection function for this instance
+*/
+function getOrCreateClearSelection(mapId) {
+	let clearSelection = clearSelectionCache.get(mapId);
+	if (!clearSelection) {
+		clearSelection = () => {
+			shapeBus.emit(ShapeEvents.deselected, { mapId });
+		};
+		clearSelectionCache.set(mapId, clearSelection);
+	}
+	return clearSelection;
+}
+/**
+* Get the current selected shape ID for a given map instance (direct access, not reactive).
+* @internal - For internal map-toolkit use only
+*
+* @param mapId - The unique identifier for the map instance
+* @returns The currently selected shape ID, or undefined
+*/
+function getSelectedShapeId(mapId) {
+	return getSnapshot(mapId);
+}
+/**
+* Manually clear all selection state for a specific mapId.
+* 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 mapId - The unique identifier for the map instance to clear
+*
+* @example
+* ```tsx
+* // Manual cleanup (rarely needed)
+* clearSelectionState('my-map-instance');
+* ```
+*/
+function clearSelectionState(mapId) {
+	const unsub = busUnsubscribers.get(mapId);
+	if (unsub) {
+		unsub();
+		busUnsubscribers.delete(mapId);
+	}
+	clearAllCaches(mapId);
+}
+
+//#endregion
+export { clearSelectionState, getOrCreateClearSelection, getOrCreateServerSnapshot, getOrCreateSetSelectedId, getOrCreateSnapshot, getOrCreateSubscription, getSelectedShapeId };
+//# sourceMappingURL=store.js.map

package/dist/deckgl/shapes/display-shape-layer/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/store.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Shape Selection Store\n *\n * This module provides a store pattern for managing shape selection state,\n * designed to work with React's `useSyncExternalStore` hook.\n *\n * ## Architecture\n *\n * The store uses a fan-out pattern similar to `map-cursor/store.ts` and `map-mode/store.ts`:\n * - **1 bus listener per mapId** - Regardless of how many React components subscribe\n * - **N React subscribers** - Each component gets notified via `useSyncExternalStore`\n * - **Automatic cleanup** - Bus listeners are removed when the last subscriber unmounts\n *\n * ## Why This Pattern?\n *\n * Without this pattern, using `useOn` directly in each React component would\n * create N bus listeners for N components subscribing to the same events.\n * The fan-out pattern ensures exactly 1 bus listener per mapId, regardless\n * of how many React components need the state. This also provides proper\n * cleanup semantics that prevent listener accumulation during HMR.\n *\n * ## Usage\n *\n * This module is internal to `useShapeSelection`. Use the hook instead:\n *\n * ```tsx\n * import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';\n *\n * const { selectedId, setSelectedId, clearSelection } = useShapeSelection(mapId);\n * ```\n *\n * @module\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapEvents } from '../../base-map/events';\nimport { type ShapeEvent, ShapeEvents } from '../shared/events';\nimport type { UniqueId } from '@accelint/core';\nimport type { MapClickEvent, MapEventType } from '../../base-map/types';\nimport type { ShapeId } from '../shared/types';\n\n/**\n * Typed event bus instances for shape and map events\n */\nconst shapeBus = Broadcast.getInstance<ShapeEvent>();\nconst mapBus = Broadcast.getInstance<MapEventType>();\n\n/**\n * Type representing the state for a single shape selection instance\n */\ntype ShapeSelectionState = {\n  /** Currently selected shape ID, or undefined if nothing selected */\n  selectedId: ShapeId | undefined;\n};\n\n/**\n * Store for shape selection state keyed by mapId\n */\nconst selectionStore = new Map<UniqueId, ShapeSelectionState>();\n\n/**\n * Track React component subscribers per mapId (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 mapId).\n * This ensures we only have one bus listener per map instance, 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 mapId to avoid recreating on every render\n */\nconst subscriptionCache = new Map<UniqueId, Subscription>();\n\n/**\n * Cache of snapshot functions per mapId to maintain referential stability\n */\nconst snapshotCache = new Map<UniqueId, () => ShapeId | undefined>();\n\n/**\n * Cache of server snapshot functions per mapId to maintain referential stability.\n * Server snapshots always return undefined since selection state is client-only.\n */\nconst serverSnapshotCache = new Map<UniqueId, () => ShapeId | undefined>();\n\n/**\n * Cache of setSelectedId functions per mapId to maintain referential stability\n */\nconst setSelectedIdCache = new Map<\n  UniqueId,\n  (id: ShapeId | undefined) => void\n>();\n\n/**\n * Cache of clearSelection functions per mapId to maintain referential stability\n */\nconst clearSelectionCache = new Map<UniqueId, () => void>();\n\n/**\n * All state caches that need cleanup when an instance is removed\n */\nconst stateCaches = [\n  selectionStore,\n  componentSubscribers,\n  subscriptionCache,\n  snapshotCache,\n  serverSnapshotCache,\n  setSelectedIdCache,\n  clearSelectionCache,\n] as const;\n\n/**\n * Clear all cached state for a given mapId\n */\nfunction clearAllCaches(mapId: UniqueId): void {\n  for (const cache of stateCaches) {\n    cache.delete(mapId);\n  }\n}\n\n/**\n * Get or create selection state for a given mapId\n */\nfunction getOrCreateState(mapId: UniqueId): ShapeSelectionState {\n  if (!selectionStore.has(mapId)) {\n    selectionStore.set(mapId, {\n      selectedId: undefined,\n    });\n  }\n  // biome-ignore lint/style/noNonNullAssertion: State guaranteed to exist after has() check above\n  return selectionStore.get(mapId)!;\n}\n\n/**\n * Get current selection snapshot for a given map instance (for useSyncExternalStore)\n */\nfunction getSnapshot(mapId: UniqueId): ShapeId | undefined {\n  const state = selectionStore.get(mapId);\n  return state?.selectedId;\n}\n\n/**\n * Notify all React subscribers for a given mapId\n */\nfunction notifySubscribers(mapId: UniqueId): void {\n  const subscribers = componentSubscribers.get(mapId);\n  if (subscribers) {\n    for (const onStoreChange of subscribers) {\n      onStoreChange();\n    }\n  }\n}\n\n/**\n * Ensures a single bus listener exists for the given mapId.\n * All React subscribers will be notified via fan-out when the bus events fire.\n * This prevents creating N bus listeners for N React components.\n *\n * @param mapId - The unique identifier for the map instance\n */\nfunction ensureBusListener(mapId: UniqueId): void {\n  if (busUnsubscribers.has(mapId)) {\n    return; // Already listening\n  }\n\n  const state = getOrCreateState(mapId);\n\n  // Listen for shape selection events\n  const unsubSelected = shapeBus.on(ShapeEvents.selected, (event) => {\n    if (event.payload.mapId !== mapId) {\n      return;\n    }\n    const previousId = state.selectedId;\n    state.selectedId = event.payload.shapeId;\n    if (previousId !== state.selectedId) {\n      notifySubscribers(mapId);\n    }\n  });\n\n  // Listen for shape deselection events\n  const unsubDeselected = shapeBus.on(ShapeEvents.deselected, (event) => {\n    if (event.payload.mapId !== mapId) {\n      return;\n    }\n    const previousId = state.selectedId;\n    state.selectedId = undefined;\n    if (previousId !== state.selectedId) {\n      notifySubscribers(mapId);\n    }\n  });\n\n  // Listen for map clicks to detect clicks on empty space\n  const unsubClick = mapBus.on(MapEvents.click, (event: MapClickEvent) => {\n    // Only emit deselect if we have a selection and clicked on empty space\n    // index is -1 when nothing is picked\n    if (\n      state.selectedId &&\n      event.payload.id === mapId &&\n      event.payload.info.index === -1\n    ) {\n      // Emit deselection event - this will be caught by our deselected listener above\n      shapeBus.emit(ShapeEvents.deselected, { mapId });\n    }\n  });\n\n  // Store composite cleanup function\n  busUnsubscribers.set(mapId, () => {\n    unsubSelected();\n    unsubDeselected();\n    unsubClick();\n  });\n}\n\n/**\n * Cleans up the bus listener if no React subscribers remain.\n *\n * @param mapId - The unique identifier for the map instance\n */\nfunction cleanupBusListenerIfNeeded(mapId: UniqueId): void {\n  const subscribers = componentSubscribers.get(mapId);\n\n  if (!subscribers || subscribers.size === 0) {\n    // No more React subscribers - clean up bus listener\n    const unsub = busUnsubscribers.get(mapId);\n    if (unsub) {\n      unsub();\n      busUnsubscribers.delete(mapId);\n    }\n\n    // Clean up all state\n    clearAllCaches(mapId);\n  }\n}\n\n/**\n * Creates or retrieves a cached subscription function for a given mapId.\n * Uses a fan-out pattern: 1 bus listener -> N React subscribers.\n * Automatically cleans up selection state when the last subscriber unsubscribes.\n *\n * @param mapId - The unique identifier for the map instance\n * @returns A subscription function for useSyncExternalStore\n */\nexport function getOrCreateSubscription(\n  mapId: UniqueId,\n): (onStoreChange: () => void) => () => void {\n  let subscription = subscriptionCache.get(mapId);\n  if (!subscription) {\n    subscription = (onStoreChange: () => void) => {\n      // Ensure state exists\n      getOrCreateState(mapId);\n\n      // Ensure single bus listener exists for this mapId\n      ensureBusListener(mapId);\n\n      // Get or create the subscriber set for this map instance, then add this component's callback\n      let subscriberSet = componentSubscribers.get(mapId);\n      if (!subscriberSet) {\n        subscriberSet = new Set();\n        componentSubscribers.set(mapId, subscriberSet);\n      }\n      subscriberSet.add(onStoreChange);\n\n      // Return cleanup function to remove this component's subscription\n      return () => {\n        const currentSubscriberSet = componentSubscribers.get(mapId);\n        if (currentSubscriberSet) {\n          currentSubscriberSet.delete(onStoreChange);\n        }\n\n        // Clean up bus listener if this was the last React subscriber\n        cleanupBusListenerIfNeeded(mapId);\n      };\n    };\n\n    subscriptionCache.set(mapId, subscription);\n  }\n\n  return subscription;\n}\n\n/**\n * Creates or retrieves a cached snapshot function for a given mapId.\n * The selection ID returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.\n *\n * @param mapId - The unique identifier for the map instance\n * @returns A snapshot function for useSyncExternalStore\n */\nexport function getOrCreateSnapshot(\n  mapId: UniqueId,\n): () => ShapeId | undefined {\n  let snapshot = snapshotCache.get(mapId);\n  if (!snapshot) {\n    snapshot = () => getSnapshot(mapId);\n    snapshotCache.set(mapId, snapshot);\n  }\n\n  return snapshot;\n}\n\n/**\n * Creates or retrieves a cached server snapshot function for a given mapId.\n * Server snapshots always return undefined since selection state is client-only.\n * Required for SSR/RSC compatibility with useSyncExternalStore.\n *\n * @param mapId - The unique identifier for the map instance\n * @returns A server snapshot function for useSyncExternalStore\n */\nexport function getOrCreateServerSnapshot(\n  mapId: UniqueId,\n): () => ShapeId | undefined {\n  let serverSnapshot = serverSnapshotCache.get(mapId);\n  if (!serverSnapshot) {\n    serverSnapshot = () => undefined;\n    serverSnapshotCache.set(mapId, serverSnapshot);\n  }\n\n  return serverSnapshot;\n}\n\n/**\n * Creates or retrieves a cached setSelectedId function for a given mapId.\n * This maintains referential stability for the function reference.\n *\n * @param mapId - The unique identifier for the map instance\n * @returns A setSelectedId function for this instance\n */\nexport function getOrCreateSetSelectedId(\n  mapId: UniqueId,\n): (id: ShapeId | undefined) => void {\n  let setSelectedId = setSelectedIdCache.get(mapId);\n  if (!setSelectedId) {\n    setSelectedId = (id: ShapeId | undefined) => {\n      const state = getOrCreateState(mapId);\n      const previousId = state.selectedId;\n\n      if (id === undefined && previousId !== undefined) {\n        // Emit deselection event\n        shapeBus.emit(ShapeEvents.deselected, { mapId });\n      } else if (id !== undefined && previousId !== id) {\n        // Emit selection event\n        shapeBus.emit(ShapeEvents.selected, { shapeId: id, mapId });\n      }\n    };\n\n    setSelectedIdCache.set(mapId, setSelectedId);\n  }\n\n  return setSelectedId;\n}\n\n/**\n * Creates or retrieves a cached clearSelection function for a given mapId.\n * This maintains referential stability for the function reference.\n *\n * Note: This always emits a deselected event, even if nothing is currently selected.\n * This matches the original behavior and allows consumers to use clearSelection\n * as a \"force deselect\" without needing to check selection state first.\n *\n * @param mapId - The unique identifier for the map instance\n * @returns A clearSelection function for this instance\n */\nexport function getOrCreateClearSelection(mapId: UniqueId): () => void {\n  let clearSelection = clearSelectionCache.get(mapId);\n  if (!clearSelection) {\n    clearSelection = () => {\n      shapeBus.emit(ShapeEvents.deselected, { mapId });\n    };\n\n    clearSelectionCache.set(mapId, clearSelection);\n  }\n\n  return clearSelection;\n}\n\n/**\n * Get the current selected shape ID for a given map instance (direct access, not reactive).\n * @internal - For internal map-toolkit use only\n *\n * @param mapId - The unique identifier for the map instance\n * @returns The currently selected shape ID, or undefined\n */\nexport function getSelectedShapeId(mapId: UniqueId): ShapeId | undefined {\n  return getSnapshot(mapId);\n}\n\n/**\n * Manually clear all selection state for a specific mapId.\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 mapId - The unique identifier for the map instance to clear\n *\n * @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearSelectionState('my-map-instance');\n * ```\n */\nexport function clearSelectionState(mapId: UniqueId): void {\n  // Unsubscribe from bus if listening\n  const unsub = busUnsubscribers.get(mapId);\n  if (unsub) {\n    unsub();\n    busUnsubscribers.delete(mapId);\n  }\n\n  // Clear all state\n  clearAllCaches(mapId);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,MAAM,WAAW,UAAU,aAAyB;AACpD,MAAM,SAAS,UAAU,aAA2B;;;;AAapD,MAAM,iCAAiB,IAAI,KAAoC;;;;;AAM/D,MAAM,uCAAuB,IAAI,KAAgC;;;;;;AAOjE,MAAM,mCAAmB,IAAI,KAA2B;;;;AAMxD,MAAM,oCAAoB,IAAI,KAA6B;;;;AAK3D,MAAM,gCAAgB,IAAI,KAA0C;;;;;AAMpE,MAAM,sCAAsB,IAAI,KAA0C;;;;AAK1E,MAAM,qCAAqB,IAAI,KAG5B;;;;AAKH,MAAM,sCAAsB,IAAI,KAA2B;;;;AAK3D,MAAM,cAAc;CAClB;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;AAKD,SAAS,eAAe,OAAuB;AAC7C,MAAK,MAAM,SAAS,YAClB,OAAM,OAAO,MAAM;;;;;AAOvB,SAAS,iBAAiB,OAAsC;AAC9D,KAAI,CAAC,eAAe,IAAI,MAAM,CAC5B,gBAAe,IAAI,OAAO,EACxB,YAAY,QACb,CAAC;AAGJ,QAAO,eAAe,IAAI,MAAM;;;;;AAMlC,SAAS,YAAY,OAAsC;AAEzD,QADc,eAAe,IAAI,MAAM,EACzB;;;;;AAMhB,SAAS,kBAAkB,OAAuB;CAChD,MAAM,cAAc,qBAAqB,IAAI,MAAM;AACnD,KAAI,YACF,MAAK,MAAM,iBAAiB,YAC1B,gBAAe;;;;;;;;;AAYrB,SAAS,kBAAkB,OAAuB;AAChD,KAAI,iBAAiB,IAAI,MAAM,CAC7B;CAGF,MAAM,QAAQ,iBAAiB,MAAM;CAGrC,MAAM,gBAAgB,SAAS,GAAG,YAAY,WAAW,UAAU;AACjE,MAAI,MAAM,QAAQ,UAAU,MAC1B;EAEF,MAAM,aAAa,MAAM;AACzB,QAAM,aAAa,MAAM,QAAQ;AACjC,MAAI,eAAe,MAAM,WACvB,mBAAkB,MAAM;GAE1B;CAGF,MAAM,kBAAkB,SAAS,GAAG,YAAY,aAAa,UAAU;AACrE,MAAI,MAAM,QAAQ,UAAU,MAC1B;EAEF,MAAM,aAAa,MAAM;AACzB,QAAM,aAAa;AACnB,MAAI,eAAe,MAAM,WACvB,mBAAkB,MAAM;GAE1B;CAGF,MAAM,aAAa,OAAO,GAAG,UAAU,QAAQ,UAAyB;AAGtE,MACE,MAAM,cACN,MAAM,QAAQ,OAAO,SACrB,MAAM,QAAQ,KAAK,UAAU,GAG7B,UAAS,KAAK,YAAY,YAAY,EAAE,OAAO,CAAC;GAElD;AAGF,kBAAiB,IAAI,aAAa;AAChC,iBAAe;AACf,mBAAiB;AACjB,cAAY;GACZ;;;;;;;AAQJ,SAAS,2BAA2B,OAAuB;CACzD,MAAM,cAAc,qBAAqB,IAAI,MAAM;AAEnD,KAAI,CAAC,eAAe,YAAY,SAAS,GAAG;EAE1C,MAAM,QAAQ,iBAAiB,IAAI,MAAM;AACzC,MAAI,OAAO;AACT,UAAO;AACP,oBAAiB,OAAO,MAAM;;AAIhC,iBAAe,MAAM;;;;;;;;;;;AAYzB,SAAgB,wBACd,OAC2C;CAC3C,IAAI,eAAe,kBAAkB,IAAI,MAAM;AAC/C,KAAI,CAAC,cAAc;AACjB,kBAAgB,kBAA8B;AAE5C,oBAAiB,MAAM;AAGvB,qBAAkB,MAAM;GAGxB,IAAI,gBAAgB,qBAAqB,IAAI,MAAM;AACnD,OAAI,CAAC,eAAe;AAClB,oCAAgB,IAAI,KAAK;AACzB,yBAAqB,IAAI,OAAO,cAAc;;AAEhD,iBAAc,IAAI,cAAc;AAGhC,gBAAa;IACX,MAAM,uBAAuB,qBAAqB,IAAI,MAAM;AAC5D,QAAI,qBACF,sBAAqB,OAAO,cAAc;AAI5C,+BAA2B,MAAM;;;AAIrC,oBAAkB,IAAI,OAAO,aAAa;;AAG5C,QAAO;;;;;;;;;AAUT,SAAgB,oBACd,OAC2B;CAC3B,IAAI,WAAW,cAAc,IAAI,MAAM;AACvC,KAAI,CAAC,UAAU;AACb,mBAAiB,YAAY,MAAM;AACnC,gBAAc,IAAI,OAAO,SAAS;;AAGpC,QAAO;;;;;;;;;;AAWT,SAAgB,0BACd,OAC2B;CAC3B,IAAI,iBAAiB,oBAAoB,IAAI,MAAM;AACnD,KAAI,CAAC,gBAAgB;AACnB,yBAAuB;AACvB,sBAAoB,IAAI,OAAO,eAAe;;AAGhD,QAAO;;;;;;;;;AAUT,SAAgB,yBACd,OACmC;CACnC,IAAI,gBAAgB,mBAAmB,IAAI,MAAM;AACjD,KAAI,CAAC,eAAe;AAClB,mBAAiB,OAA4B;GAE3C,MAAM,aADQ,iBAAiB,MAAM,CACZ;AAEzB,OAAI,OAAO,UAAa,eAAe,OAErC,UAAS,KAAK,YAAY,YAAY,EAAE,OAAO,CAAC;YACvC,OAAO,UAAa,eAAe,GAE5C,UAAS,KAAK,YAAY,UAAU;IAAE,SAAS;IAAI;IAAO,CAAC;;AAI/D,qBAAmB,IAAI,OAAO,cAAc;;AAG9C,QAAO;;;;;;;;;;;;;AAcT,SAAgB,0BAA0B,OAA6B;CACrE,IAAI,iBAAiB,oBAAoB,IAAI,MAAM;AACnD,KAAI,CAAC,gBAAgB;AACnB,yBAAuB;AACrB,YAAS,KAAK,YAAY,YAAY,EAAE,OAAO,CAAC;;AAGlD,sBAAoB,IAAI,OAAO,eAAe;;AAGhD,QAAO;;;;;;;;;AAUT,SAAgB,mBAAmB,OAAsC;AACvE,QAAO,YAAY,MAAM;;;;;;;;;;;;;;;AAgB3B,SAAgB,oBAAoB,OAAuB;CAEzD,MAAM,QAAQ,iBAAiB,IAAI,MAAM;AACzC,KAAI,OAAO;AACT,SAAO;AACP,mBAAiB,OAAO,MAAM;;AAIhC,gBAAe,MAAM"}

package/dist/deckgl/shapes/display-shape-layer/types.d.ts

@@ -0,0 +1,115 @@
+/*
+ * 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 { EditableShape, ShapeId, StyledFeature as StyledFeature$1 } from "../shared/types.js";
+import { LabelPositionOptions } from "./utils/labels.js";
+import { UniqueId } from "@accelint/core";
+import { CompositeLayerProps } from "@deck.gl/core";
+
+//#region src/deckgl/shapes/display-shape-layer/types.d.ts
+/**
+ * Re-export StyledFeature from shared types
+ */
+type StyledFeature = StyledFeature$1;
+/**
+ * Re-export StyledFeatureProperties from shared types
+ */
+type StyledFeatureProperties = StyledFeature$1['properties'];
+/**
+ * Props for DisplayShapeLayer
+ *
+ * @example Basic usage
+ * ```tsx
+ * const props: DisplayShapeLayerProps = {
+ *   id: 'my-shapes',
+ *   data: myShapes,
+ *   pickable: true,
+ *   showLabels: true,
+ * };
+ * ```
+ */
+interface DisplayShapeLayerProps extends CompositeLayerProps {
+  /** Unique layer ID - required for deck.gl layer management */
+  id: string;
+  /**
+   * Map instance ID for event bus isolation in multi-map scenarios.
+   * Shape events will include this ID in their payload,
+   * allowing listeners to filter events by map instance.
+   */
+  mapId: UniqueId;
+  /**
+   * Array of shapes to display
+   * Each shape must have a GeoJSON feature with styleProperties
+   */
+  data: EditableShape[];
+  /**
+   * Currently selected shape ID (for highlighting)
+   * When set, renders a highlight layer around the selected shape
+   */
+  selectedShapeId?: ShapeId;
+  /**
+   * Callback when a shape is clicked
+   * Also triggers a shapes:selected event on the event bus
+   * @param shape - The clicked shape with full properties
+   */
+  onShapeClick?: (shape: EditableShape) => void;
+  /**
+   * Callback when a shape is hovered
+   * Called with null when hover ends
+   * @param shape - The hovered shape, or null when hover ends
+   */
+  onShapeHover?: (shape: EditableShape | null) => void;
+  /**
+   * Whether to show labels on shapes
+   * Labels use the shape's `label` property, or `name` if label is not set
+   * @default true
+   */
+  showLabels?: boolean;
+  /**
+   * Global label positioning options
+   * Can be overridden per-shape via styleProperties
+   * Priority: per-shape properties > labelOptions > defaults
+   * @see LabelPositionOptions for available options
+   */
+  labelOptions?: LabelPositionOptions;
+  /**
+   * Whether to show the highlight layer around selected shapes
+   * When false, no highlight effect is rendered even when a shape is selected
+   * @default false
+   */
+  showHighlight?: boolean;
+  /**
+   * Custom highlight color for selected shapes [r, g, b, a]
+   * Each channel is 0-255
+   * @default [40, 245, 190, 100] - Turquoise at ~39% opacity
+   * @example Custom red highlight
+   * ```tsx
+   * highlightColor={[255, 0, 0, 128]} // Red at 50% opacity
+   * ```
+   */
+  highlightColor?: [number, number, number, number];
+  /**
+   * When true (default), applies 60% opacity multiplier to fill colors for standard semi-transparent look.
+   * This is a convenience prop for achieving the standard map shape appearance.
+   * When false, colors are rendered exactly as specified in styleProperties.
+   * @default true
+   * @example Standard semi-transparent fills
+   * ```tsx
+   * <DisplayShapeLayer data={shapes} applyBaseOpacity />
+   * // Shape with fillColor [98, 166, 255, 255] renders at alpha 153
+   * ```
+   */
+  applyBaseOpacity?: boolean;
+}
+//#endregion
+export { DisplayShapeLayerProps, StyledFeature, StyledFeatureProperties };
+//# sourceMappingURL=types.d.ts.map

package/dist/deckgl/shapes/display-shape-layer/types.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+

package/dist/deckgl/shapes/display-shape-layer/use-shape-selection.d.ts

@@ -0,0 +1,89 @@
+/*
+ * 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 { ShapeId } from "../shared/types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/deckgl/shapes/display-shape-layer/use-shape-selection.d.ts
+/**
+ * Return type for useShapeSelection hook
+ */
+interface UseShapeSelectionReturn {
+  /** Currently selected shape ID, or undefined if nothing selected */
+  selectedId: ShapeId | undefined;
+  /** Manually set the selected shape ID (useful for programmatic selection) */
+  setSelectedId: (id: ShapeId | undefined) => void;
+  /** Manually clear the selection */
+  clearSelection: () => void;
+}
+/**
+ * Hook to manage shape selection state with automatic deselection
+ *
+ * This hook encapsulates the common pattern of:
+ * 1. Listening to `shapes:selected` events and updating state
+ * 2. Listening to `shapes:deselected` events and clearing state
+ * 3. Listening to map clicks on empty space and emitting `shapes:deselected`
+ *
+ * Uses a store pattern with `useSyncExternalStore` for proper listener cleanup
+ * during HMR (Hot Module Replacement) in development. The store ensures only
+ * one bus listener exists per map instance, regardless of how many React
+ * components subscribe.
+ *
+ * @param mapId - The map instance ID for event filtering
+ * @returns Selection state and control functions
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';
+ *
+ * function MapWithShapes() {
+ *   const { selectedId } = useShapeSelection(MAP_ID);
+ *
+ *   return (
+ *     <BaseMap id={MAP_ID}>
+ *       <displayShapeLayer
+ *         id="shapes"
+ *         mapId={MAP_ID}
+ *         data={shapes}
+ *         selectedShapeId={selectedId}
+ *       />
+ *     </BaseMap>
+ *   );
+ * }
+ * ```
+ *
+ * @example With programmatic selection control
+ * ```tsx
+ * function MapWithShapes() {
+ *   const { selectedId, setSelectedId, clearSelection } = useShapeSelection(MAP_ID);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setSelectedId(shapes[0].id)}>Select First Shape</button>
+ *       <button onClick={clearSelection}>Clear Selection</button>
+ *       <BaseMap id={MAP_ID}>
+ *         <displayShapeLayer
+ *           id="shapes"
+ *           mapId={MAP_ID}
+ *           data={shapes}
+ *           selectedShapeId={selectedId}
+ *         />
+ *       </BaseMap>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useShapeSelection(mapId: UniqueId): UseShapeSelectionReturn;
+//#endregion
+export { UseShapeSelectionReturn, useShapeSelection };
+//# sourceMappingURL=use-shape-selection.d.ts.map