@accelint/map-toolkit 0.3.1 → 0.4.1

package/dist/maplibre/hooks/use-maplibre.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/maplibre/hooks/use-maplibre.ts"],"names":["MapLibre"],"mappings":";;;AAiDO,SAAS,WAAA,CACd,IAAA,EACA,QAAA,EACA,OAAA,EACA;AACA,EAAA,MAAM,MAAA,GAAS,OAAwB,IAAI,CAAA;AAG3C,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AAEjC,EAAA,MAAM,QAAA,GAAW,OAAO,QAAQ,CAAA;AAGhC,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,IAAQ,CAAC,MAAA,CAAO,OAAA,EAAS;AAC3B,MAAA,MAAA,CAAO,OAAA,GAAU,IAAIA,GAAA,CAAS;AAAA,QAC5B,GAAG,UAAA,CAAW,OAAA;AAAA,QACd,OAAO,QAAA,CAAS;AAAA,OACjB,CAAA;AAED,MAAA,MAAA,CAAO,OAAA,CAAQ,IAAA,CAAK,YAAA,EAAc,MAAM;AACtC,QAAA,MAAA,CAAO,OAAA,EAAS,aAAA,CAAc,EAAE,IAAA,EAAM,YAAY,CAAA;AAClD,QAAA,MAAA,CAAO,OAAA,EAAS,WAAW,IAAI,CAAA;AAAA,MACjC,CAAC,CAAA;AAED,MAAA,OAAO,MAAM;AACX,QAAA,IAAI,OAAO,OAAA,EAAS;AAClB,UAAA,MAAA,CAAO,OAAA,CAAQ,cAAc,IAAI,CAAA;AACjC,UAAA,MAAA,CAAO,QAAQ,MAAA,EAAO;AACtB,UAAA,MAAA,CAAO,OAAA,GAAU,IAAA;AAAA,QACnB;AAAA,MACF,CAAA;AAAA,IACF;AAAA,EACF,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AAGT,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,OAAO,OAAA,EAAS;AAClB,MAAA,MAAA,CAAO,OAAA,CAAQ,SAAS,QAAQ,CAAA;AAAA,IAClC;AAAA,EACF,CAAA,EAAG,CAAC,QAAQ,CAAC,CAAA;AAEb,EAAA,OAAO,MAAA,CAAO,OAAA;AAChB","file":"use-maplibre.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\nimport { type IControl, Map as MapLibre, type MapOptions } from 'maplibre-gl';\nimport { useEffect, useRef } from 'react';\n\n/**\n * Hook to integrate a MapLibre GL map with a Deck.gl instance.\n *\n * This hook manages the lifecycle of a MapLibre map, including initialization,\n * style updates, and cleanup. It ensures the Deck.gl control is properly added\n * to the map and handles cleanup when the component unmounts.\n *\n * @param deck - The Deck.gl IControl instance to add to the map\n * @param styleUrl - The MapLibre style URL to use for the map\n * @param options - MapLibre map options (container, center, zoom, etc.)\n * @returns The MapLibre map instance, or null if not yet initialized\n *\n * @example\n * ```tsx\n * function MapComponent() {\n *   const deckglInstance = useDeckgl();\n *   const container = useId();\n *\n *   const mapOptions = useMemo(() => ({\n *     container,\n *     center: [-122.4, 37.8],\n *     zoom: 12,\n *   }), [container]);\n *\n *   useMapLibre(\n *     deckglInstance as IControl,\n *     'https://tiles.example.com/style.json',\n *     mapOptions\n *   );\n *\n *   return <div id={container} />;\n * }\n * ```\n */\nexport function useMapLibre(\n  deck: IControl | null,\n  styleUrl: string,\n  options: MapOptions,\n) {\n  const mapRef = useRef<MapLibre | null>(null);\n  // Using a ref for options to avoid re-creating the map when options object reference changes\n  // The map is only created once on mount, options changes after that are ignored\n  const optionsRef = useRef(options);\n  // using a ref in the initial setup so that it doesn't cause a re-run of the effect on change\n  const styleRef = useRef(styleUrl);\n\n  // Initialize MapLibre instance once\n  useEffect(() => {\n    if (deck && !mapRef.current) {\n      mapRef.current = new MapLibre({\n        ...optionsRef.current,\n        style: styleRef.current,\n      });\n\n      mapRef.current.once('style.load', () => {\n        mapRef.current?.setProjection({ type: 'mercator' });\n        mapRef.current?.addControl(deck);\n      });\n\n      return () => {\n        if (mapRef.current) {\n          mapRef.current.removeControl(deck);\n          mapRef.current.remove();\n          mapRef.current = null;\n        }\n      };\n    }\n  }, [deck]);\n\n  // Update style when it changes\n  useEffect(() => {\n    if (mapRef.current) {\n      mapRef.current.setStyle(styleUrl);\n    }\n  }, [styleUrl]);\n\n  return mapRef.current;\n}\n"]}
+{"version":3,"file":"use-maplibre.js","names":["MapLibre"],"sources":["../../../src/maplibre/hooks/use-maplibre.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 { type IControl, Map as MapLibre, type MapOptions } from 'maplibre-gl';\nimport { useEffect, useRef } from 'react';\n\n/**\n * Hook to integrate a MapLibre GL map with a Deck.gl instance.\n *\n * This hook manages the lifecycle of a MapLibre map, including initialization,\n * style updates, and cleanup. It ensures the Deck.gl control is properly added\n * to the map and handles cleanup when the component unmounts.\n *\n * @param deck - The Deck.gl IControl instance to add to the map\n * @param styleUrl - The MapLibre style URL to use for the map\n * @param options - MapLibre map options (container, center, zoom, etc.)\n * @returns The MapLibre map instance, or null if not yet initialized\n *\n * @example\n * ```tsx\n * function MapComponent() {\n *   const deckglInstance = useDeckgl();\n *   const container = useId();\n *\n *   const mapOptions = useMemo(() => ({\n *     container,\n *     center: [-122.4, 37.8],\n *     zoom: 12,\n *   }), [container]);\n *\n *   useMapLibre(\n *     deckglInstance as IControl,\n *     'https://tiles.example.com/style.json',\n *     mapOptions\n *   );\n *\n *   return <div id={container} />;\n * }\n * ```\n */\nexport function useMapLibre(\n  deck: IControl | null,\n  styleUrl: string,\n  options: MapOptions,\n) {\n  const mapRef = useRef<MapLibre | null>(null);\n  // Using a ref for options to avoid re-creating the map when options object reference changes\n  // The map is only created once on mount, options changes after that are ignored\n  const optionsRef = useRef(options);\n  // using a ref in the initial setup so that it doesn't cause a re-run of the effect on change\n  const styleRef = useRef(styleUrl);\n\n  // Initialize MapLibre instance once\n  useEffect(() => {\n    if (deck && !mapRef.current) {\n      mapRef.current = new MapLibre({\n        ...optionsRef.current,\n        style: styleRef.current,\n      });\n\n      mapRef.current.once('style.load', () => {\n        mapRef.current?.setProjection({ type: 'mercator' });\n        mapRef.current?.addControl(deck);\n      });\n\n      return () => {\n        if (mapRef.current) {\n          mapRef.current.removeControl(deck);\n          mapRef.current.remove();\n          mapRef.current = null;\n        }\n      };\n    }\n  }, [deck]);\n\n  // Update style when it changes\n  useEffect(() => {\n    if (mapRef.current) {\n      mapRef.current.setStyle(styleUrl);\n    }\n  }, [styleUrl]);\n\n  return mapRef.current;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,SAAgB,YACd,MACA,UACA,SACA;CACA,MAAM,SAAS,OAAwB,KAAK;CAG5C,MAAM,aAAa,OAAO,QAAQ;CAElC,MAAM,WAAW,OAAO,SAAS;AAGjC,iBAAgB;AACd,MAAI,QAAQ,CAAC,OAAO,SAAS;AAC3B,UAAO,UAAU,IAAIA,IAAS;IAC5B,GAAG,WAAW;IACd,OAAO,SAAS;IACjB,CAAC;AAEF,UAAO,QAAQ,KAAK,oBAAoB;AACtC,WAAO,SAAS,cAAc,EAAE,MAAM,YAAY,CAAC;AACnD,WAAO,SAAS,WAAW,KAAK;KAChC;AAEF,gBAAa;AACX,QAAI,OAAO,SAAS;AAClB,YAAO,QAAQ,cAAc,KAAK;AAClC,YAAO,QAAQ,QAAQ;AACvB,YAAO,UAAU;;;;IAItB,CAAC,KAAK,CAAC;AAGV,iBAAgB;AACd,MAAI,OAAO,QACT,QAAO,QAAQ,SAAS,SAAS;IAElC,CAAC,SAAS,CAAC;AAEd,QAAO,OAAO"}

package/dist/maplibre/index.d.ts

@@ -1,3 +1,15 @@
-export { INITIAL_VIEW_STATE } from './constants.js';
-export { useMapLibre } from './hooks/use-maplibre.js';
-import 'maplibre-gl';
+/*
+ * 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 { INITIAL_VIEW_STATE } from "./constants.js";
+import { useMapLibre } from "./hooks/use-maplibre.js";
+export { INITIAL_VIEW_STATE, useMapLibre };

package/dist/maplibre/index.js

@@ -1,4 +1,17 @@
-export { INITIAL_VIEW_STATE } from './constants.js';
-export { useMapLibre } from './hooks/use-maplibre.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+/*
+ * 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 { INITIAL_VIEW_STATE } from "./constants.js";
+import { useMapLibre } from "./hooks/use-maplibre.js";
+
+export { INITIAL_VIEW_STATE, useMapLibre };

package/dist/viewport/constants.d.ts

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

package/dist/viewport/constants.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/viewport/constants.ts"],"names":[],"mappings":"AAYO,MAAM,QAAA,GAAW;AAAA,EACtB,EAAA,EAAI,YAAA;AAAA,EACJ,CAAA,EAAG,QAAA;AAAA,EACH,EAAA,EAAI,eAAA;AAAA,EACJ,EAAA,EAAI,OAAA;AAAA,EACJ,EAAA,EAAI;AACN","file":"constants.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\nexport const UNIT_MAP = {\n  km: 'kilometers',\n  m: 'meters',\n  nm: 'nauticalmiles',\n  mi: 'miles',\n  ft: 'feet',\n} as const;\n"]}
+{"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/index.d.ts

@@ -1,13 +1,18 @@
-export { UNIT_MAP } from './constants.js';
-export { UseViewportStateProps, clearViewportState, useViewportState } from './use-viewport-state.js';
-export { getViewportSize } from './utils.js';
-export { ViewportSize, ViewportSizeProps } from './viewport-size.js';
-export { GeoCoordinate, GetViewportSizeArgs, SupportedDistanceUnit } from './types.js';
-import 'react';
-import '@accelint/core';
-import '../deckgl/base-map/types.js';
-import '@accelint/bus';
-import '@deck.gl/core';
-import 'mjolnir.js';
-import '../deckgl/base-map/events.js';
-import 'react/jsx-runtime';
+/*
+ * 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 { UNIT_MAP } from "./constants.js";
+import { UseViewportStateProps, clearViewportState, useViewportState } from "./use-viewport-state.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 };

package/dist/viewport/index.js

@@ -1,6 +1,19 @@
-export { UNIT_MAP } from './constants.js';
-export { clearViewportState, useViewportState } from './use-viewport-state.js';
-export { getViewportSize } from './utils.js';
-export { ViewportSize } from './viewport-size.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+/*
+ * 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 { UNIT_MAP } from "./constants.js";
+import { clearViewportState, useViewportState } from "./use-viewport-state.js";
+import { getViewportSize } from "./utils.js";
+import { ViewportSize } from "./viewport-size.js";
+
+export { UNIT_MAP, ViewportSize, clearViewportState, getViewportSize, useViewportState };

package/dist/viewport/types.d.ts

@@ -1,22 +1,32 @@
-import { Bounds } from '../deckgl/base-map/types.js';
-import { UNIT_MAP } from './constants.js';
-import '@accelint/bus';
-import '@accelint/core';
-import '@deck.gl/core';
-import 'mjolnir.js';
-import '../deckgl/base-map/events.js';
+/*
+ * 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 { Bounds } from "../deckgl/base-map/types.js";
+import { UNIT_MAP } from "./constants.js";
+
+//#region src/viewport/types.d.ts
 type SupportedDistanceUnit = keyof typeof UNIT_MAP;
 type GetViewportSizeArgs = {
-    bounds: Bounds;
-    zoom: number;
-    /** Viewport width in pixels */
-    width: number;
-    /** Viewport height in pixels */
-    height: number;
-    unit?: SupportedDistanceUnit;
-    formatter?: Intl.NumberFormat;
+  /** Geographic bounds, undefined if viewport not yet initialized */
+  bounds?: Bounds;
+  zoom: number;
+  /** Viewport width in pixels */
+  width: number;
+  /** Viewport height in pixels */
+  height: number;
+  unit?: SupportedDistanceUnit;
+  formatter?: Intl.NumberFormat;
 };
 type GeoCoordinate = [longitude: number, latitude: number];
-
-export type { GeoCoordinate, GetViewportSizeArgs, SupportedDistanceUnit };
+//#endregion
+export { GeoCoordinate, GetViewportSizeArgs, SupportedDistanceUnit };
+//# sourceMappingURL=types.d.ts.map

package/dist/viewport/types.js

@@ -1,3 +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.
+ */
 
-//# sourceMappingURL=types.js.map
-//# sourceMappingURL=types.js.map

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

@@ -1,16 +1,25 @@
-import { useSyncExternalStore } from 'react';
-import { UniqueId } from '@accelint/core';
-import { MapViewportPayload } from '../deckgl/base-map/types.js';
-import '@accelint/bus';
-import '@deck.gl/core';
-import 'mjolnir.js';
-import '../deckgl/base-map/events.js';
+/*
+ * 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];
+  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.
@@ -66,7 +75,12 @@ type UseViewportStateProps = {
  * }
  * ```
  */
-declare function useViewportState({ instanceId, subscribe, getSnapshot, getServerSnapshot, }: UseViewportStateProps): MapViewportPayload;
+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.
@@ -81,5 +95,6 @@ declare function useViewportState({ instanceId, subscribe, getSnapshot, getServe
  * ```
  */
 declare function clearViewportState(instanceId: UniqueId): void;
-
-export { type UseViewportStateProps, clearViewportState, useViewportState };
+//#endregion
+export { UseViewportStateProps, clearViewportState, useViewportState };
+//# sourceMappingURL=use-viewport-state.d.ts.map

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

@@ -1,109 +1,222 @@
-import { Broadcast } from '@accelint/bus';
-import { useSyncExternalStore } from 'react';
-import { MapEvents } from '../deckgl/base-map/events.js';
+/*
+ * 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);
+	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);
-  }
+	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;
+	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: [Number.NaN, Number.NaN, Number.NaN, Number.NaN],
-      latitude: Number.NaN,
-      longitude: Number.NaN,
-      zoom: Number.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;
+	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;
 }
-function useViewportState({
-  instanceId,
-  subscribe,
-  getSnapshot,
-  getServerSnapshot
-}) {
-  return useSyncExternalStore(
-    subscribe ?? getOrCreateSubscription(instanceId),
-    getSnapshot ?? getOrCreateSnapshot(instanceId),
-    getServerSnapshot
-  );
+/**
+* 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);
+	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
 //# sourceMappingURL=use-viewport-state.js.map