@accelint/map-toolkit 0.4.1 → 0.6.0

package/dist/deckgl/base-map/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const MapEventsNamespace = 'map';\n\nexport const MapEvents = {\n  click: `${MapEventsNamespace}:click`,\n  hover: `${MapEventsNamespace}:hover`,\n  viewport: `${MapEventsNamespace}:viewport`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,qBAAqB;AAElC,MAAa,YAAY;CACvB,OAAO,GAAG,mBAAmB;CAC7B,OAAO,GAAG,mBAAmB;CAC7B,UAAU,GAAG,mBAAmB;CACjC"}
+{"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const MapEventsNamespace = 'map';\n\nexport const MapEvents = {\n  click: `${MapEventsNamespace}:click`,\n  hover: `${MapEventsNamespace}:hover`,\n  viewport: `${MapEventsNamespace}:viewport`,\n  // Control events\n  enablePan: `${MapEventsNamespace}:enablePan`,\n  disablePan: `${MapEventsNamespace}:disablePan`,\n  enableZoom: `${MapEventsNamespace}:enableZoom`,\n  disableZoom: `${MapEventsNamespace}:disableZoom`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,qBAAqB;AAElC,MAAa,YAAY;CACvB,OAAO,GAAG,mBAAmB;CAC7B,OAAO,GAAG,mBAAmB;CAC7B,UAAU,GAAG,mBAAmB;CAEhC,WAAW,GAAG,mBAAmB;CACjC,YAAY,GAAG,mBAAmB;CAClC,YAAY,GAAG,mBAAmB;CAClC,aAAa,GAAG,mBAAmB;CACpC"}

package/dist/deckgl/base-map/index.d.ts

@@ -10,29 +10,11 @@
  * governing permissions and limitations under the License.
  */
 
-import { UniqueId } from "@accelint/core";
-import * as react_jsx_runtime1 from "react/jsx-runtime";
-import { DeckglProps } from "@deckgl-fiber-renderer/types";
+import { BaseMapProps } from "./types.js";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/deckgl/base-map/index.d.ts
-/**
- * Props for the BaseMap component.
- * Extends all Deck.gl props and adds additional map-specific properties.
- */
-type BaseMapProps = DeckglProps & {
-  /** Optional CSS class name to apply to the map container element */
-  className?: string;
-  /**
-   * Unique identifier for this map instance (required).
-   *
-   * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).
-   * This should be a UUID generated using `uuid()` from `@accelint/core`.
-   *
-   * The same id should be passed to `useMapMode()` when accessing map mode state
-   * from components rendered outside of the BaseMap's children (i.e., as siblings).
-   */
-  id: UniqueId;
-};
+
 /**
  * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.
  *
@@ -111,15 +93,20 @@ declare function BaseMap({
   className,
   children,
   controller,
+  enableControlEvents,
   interleaved,
   parameters,
+  styleUrl,
   useDevicePixels,
   widgets: widgetsProp,
+  defaultView,
+  initialViewState,
   onClick,
   onHover,
   onViewStateChange,
+  pickingRadius,
   ...rest
-}: BaseMapProps): react_jsx_runtime1.JSX.Element;
+}: BaseMapProps): react_jsx_runtime0.JSX.Element;
 //#endregion
-export { BaseMap, BaseMapProps };
+export { BaseMap };
 //# sourceMappingURL=index.d.ts.map

package/dist/deckgl/base-map/index.js

@@ -13,16 +13,17 @@
 
 'use client';
 
+import { useCameraState } from "../../camera/use-camera-state.js";
 import { MapEvents } from "./events.js";
 import { getCursor } from "../../map-cursor/store.js";
 import { MapProvider } from "./provider.js";
-import { INITIAL_VIEW_STATE } from "../../maplibre/constants.js";
-import { useMapLibre } from "../../maplibre/hooks/use-maplibre.js";
-import { BASE_MAP_STYLE, PARAMETERS } from "./constants.js";
-import { useCallback, useId, useMemo } from "react";
-import { jsx } from "react/jsx-runtime";
+import { DARK_BASE_MAP_STYLE, DEFAULT_VIEW_STATE, PARAMETERS, PICKING_RADIUS } from "./constants.js";
+import { MapControls } from "./controls.js";
+import { useCallback, useId, useMemo, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffectEvent, useEmit } from "@accelint/bus/react";
 import { Deckgl, useDeckgl } from "@deckgl-fiber-renderer/dom";
+import { Map, useControl } from "react-map-gl/maplibre";
 
 //#region src/deckgl/base-map/index.tsx
 /**
@@ -45,6 +46,11 @@ function serializeMjolnirEvent(event) {
 	}
 	return rest;
 }
+function AddDeckglControl() {
+	const deckglInstance = useDeckgl();
+	useControl(() => deckglInstance);
+	return null;
+}
 /**
 * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.
 *
@@ -118,19 +124,44 @@ function serializeMjolnirEvent(event) {
 * }
 * ```
 */
-function BaseMap({ id, className, children, controller = true, interleaved = true, parameters = {}, useDevicePixels = false, widgets: widgetsProp = [], onClick, onHover, onViewStateChange, ...rest }) {
+function BaseMap({ id, className, children, controller = true, enableControlEvents = true, interleaved = true, parameters = {}, styleUrl = DARK_BASE_MAP_STYLE, useDevicePixels = false, widgets: widgetsProp = [], defaultView = "2D", initialViewState, onClick, onHover, onViewStateChange, pickingRadius, ...rest }) {
 	const deckglInstance = useDeckgl();
 	const container = useId();
-	useMapLibre(deckglInstance, BASE_MAP_STYLE, useMemo(() => ({
+	const mapRef = useRef(null);
+	const { cameraState, setCameraState } = useCameraState({
+		instanceId: id,
+		initialCameraState: {
+			view: defaultView,
+			zoom: initialViewState?.zoom ?? DEFAULT_VIEW_STATE.zoom,
+			latitude: initialViewState?.latitude ?? DEFAULT_VIEW_STATE.latitude,
+			longitude: initialViewState?.longitude ?? DEFAULT_VIEW_STATE.longitude
+		}
+	});
+	const viewState = useMemo(() => ({
+		...deckglInstance?._deck?._getViewState(),
+		...cameraState,
+		bearing: cameraState.rotation
+	}), [cameraState, deckglInstance?._deck?._getViewState]);
+	const mapOptions = useMemo(() => ({
 		container,
-		center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude],
-		zoom: INITIAL_VIEW_STATE.zoom,
+		zoom: viewState.zoom,
+		pitch: viewState.pitch,
+		bearing: viewState.bearing,
+		latitude: viewState.latitude,
+		longitude: viewState.longitude,
 		doubleClickZoom: false,
 		dragRotate: false,
 		pitchWithRotate: false,
 		rollEnabled: false,
-		attributionControl: { compact: true }
-	}), [container]));
+		attributionControl: { compact: true },
+		projection: cameraState.projection,
+		maxPitch: cameraState.view === "2D" ? 0 : 85
+	}), [
+		viewState,
+		container,
+		cameraState.projection,
+		cameraState.view
+	]);
 	const emitClick = useEmit(MapEvents.click);
 	const emitHover = useEmit(MapEvents.hover);
 	const emitViewport = useEmit(MapEvents.viewport);
@@ -176,43 +207,51 @@ function BaseMap({ id, className, children, controller = true, interleaved = tru
 		});
 	});
 	const handleLoad = useEffectEvent(() => {
-		deckglInstance._deck.getViewports().forEach((vp) => {
-			handleViewStateChange({
-				viewId: vp.id,
-				viewState: {
-					latitude: vp.latitude,
-					longitude: vp.longitude,
-					zoom: vp.zoom,
-					id: vp.id,
-					bounds: vp.getBounds(),
-					width: vp.width,
-					height: vp.height
-				}
-			});
+		const viewports = deckglInstance._deck.getViewports() ?? [];
+		for (const vp of viewports) handleViewStateChange({
+			viewId: vp.id,
+			viewState: {
+				latitude: vp.latitude,
+				longitude: vp.longitude,
+				zoom: vp.zoom,
+				id: vp.id,
+				bounds: vp.getBounds(),
+				width: vp.width,
+				height: vp.height
+			}
 		});
 	});
-	return /* @__PURE__ */ jsx("div", {
+	return /* @__PURE__ */ jsxs("div", {
 		id: container,
 		className,
-		children: /* @__PURE__ */ jsx(MapProvider, {
+		children: [enableControlEvents && /* @__PURE__ */ jsx(MapControls, {
+			id,
+			mapRef
+		}), /* @__PURE__ */ jsx(MapProvider, {
 			id,
-			children: /* @__PURE__ */ jsx(Deckgl, {
-				...rest,
-				controller,
-				interleaved,
-				useDevicePixels,
-				onClick: handleClick,
-				onHover: handleHover,
-				onLoad: handleLoad,
-				onViewStateChange: handleViewStateChange,
-				getCursor: handleGetCursor,
-				parameters: {
-					...PARAMETERS,
-					...parameters
-				},
-				children
+			children: /* @__PURE__ */ jsx(Map, {
+				onMove: (evt) => setCameraState(id, evt.viewState),
+				mapStyle: styleUrl,
+				ref: mapRef,
+				...mapOptions,
+				children: /* @__PURE__ */ jsxs(Deckgl, {
+					...rest,
+					interleaved,
+					getCursor: handleGetCursor,
+					useDevicePixels,
+					onClick: handleClick,
+					pickingRadius: pickingRadius ?? PICKING_RADIUS,
+					onHover: handleHover,
+					onLoad: handleLoad,
+					onViewStateChange: handleViewStateChange,
+					parameters: {
+						...PARAMETERS,
+						...parameters
+					},
+					children: [/* @__PURE__ */ jsx(AddDeckglControl, {}), children]
+				})
 			})
-		})
+		})]
 	});
 }
 

package/dist/deckgl/base-map/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/deckgl/base-map/index.tsx"],"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'use client';\n\nimport 'client-only';\nimport { useEffectEvent, useEmit } from '@accelint/bus/react';\nimport { Deckgl, useDeckgl } from '@deckgl-fiber-renderer/dom';\nimport { useCallback, useId, useMemo } from 'react';\nimport { getCursor } from '../../map-cursor/store';\nimport { INITIAL_VIEW_STATE } from '../../maplibre/constants';\nimport { useMapLibre } from '../../maplibre/hooks/use-maplibre';\nimport { BASE_MAP_STYLE, PARAMETERS } from './constants';\nimport { MapEvents } from './events';\nimport { MapProvider } from './provider';\nimport type { UniqueId } from '@accelint/core';\nimport type { PickingInfo, ViewStateChangeParameters } from '@deck.gl/core';\nimport type { DeckglProps } from '@deckgl-fiber-renderer/types';\nimport type { IControl } from 'maplibre-gl';\nimport type { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';\nimport type {\n  MapClickEvent,\n  MapHoverEvent,\n  MapViewportEvent,\n  SerializablePickingInfo,\n} from './types';\n\n/**\n * Serializes PickingInfo for event bus transmission.\n * Omits viewport, layer, and sourceLayer (contain functions) but preserves layer IDs.\n */\nfunction serializePickingInfo(info: PickingInfo): SerializablePickingInfo {\n  const { viewport, layer, sourceLayer, ...infoRest } = info;\n  return {\n    layerId: layer?.id,\n    sourceLayerId: sourceLayer?.id,\n    ...infoRest,\n  };\n}\n\n/**\n * Strips non-serializable properties from MjolnirGestureEvent for event bus transmission.\n * Removes functions, DOM elements, and PointerEvent objects that cannot be cloned.\n */\nfunction serializeMjolnirEvent(\n  event: MjolnirGestureEvent,\n): Omit<\n  MjolnirGestureEvent,\n  | 'stopPropagation'\n  | 'preventDefault'\n  | 'stopImmediatePropagation'\n  | 'srcEvent'\n  | 'rootElement'\n  | 'target'\n  | 'changedPointers'\n  | 'pointers'\n>;\n/**\n * Strips non-serializable properties from MjolnirPointerEvent for event bus transmission.\n * Removes functions and DOM elements that cannot be cloned.\n */\nfunction serializeMjolnirEvent(\n  event: MjolnirPointerEvent,\n): Omit<\n  MjolnirPointerEvent,\n  | 'stopPropagation'\n  | 'preventDefault'\n  | 'stopImmediatePropagation'\n  | 'srcEvent'\n  | 'rootElement'\n  | 'target'\n>;\nfunction serializeMjolnirEvent(\n  event: MjolnirGestureEvent | MjolnirPointerEvent,\n) {\n  const {\n    stopImmediatePropagation,\n    stopPropagation,\n    preventDefault,\n    srcEvent,\n    rootElement,\n    target,\n    ...rest\n  } = event;\n\n  // Remove pointer arrays if present (only on MjolnirGestureEvent)\n  if ('changedPointers' in rest) {\n    const { changedPointers, pointers, ...gestureRest } = rest;\n    return gestureRest;\n  }\n\n  return rest;\n}\n\n/**\n * Props for the BaseMap component.\n * Extends all Deck.gl props and adds additional map-specific properties.\n */\nexport type BaseMapProps = DeckglProps & {\n  /** Optional CSS class name to apply to the map container element */\n  className?: string;\n  /**\n   * Unique identifier for this map instance (required).\n   *\n   * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).\n   * This should be a UUID generated using `uuid()` from `@accelint/core`.\n   *\n   * The same id should be passed to `useMapMode()` when accessing map mode state\n   * from components rendered outside of the BaseMap's children (i.e., as siblings).\n   */\n  id: UniqueId;\n};\n\n/**\n * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.\n *\n * This component serves as the foundation for building interactive map applications with\n * support for click and hover events through a centralized event bus. It integrates\n * Deck.gl for 3D visualizations with MapLibre GL for the base map tiles.\n *\n * **Map Mode Integration**: BaseMap automatically creates a `MapProvider` internally,\n * which sets up the map mode state management for this instance.\n * - **Children**: Only Deck.gl layer components can be rendered as children. Custom Deck.gl\n *   layers can use `useMapMode()` without parameters to access context.\n * - **Siblings**: UI components (buttons, toolbars, etc.) must be rendered as siblings\n *   and pass `id` to `useMapMode(id)`.\n *\n * **Event Bus**: Click and hover events are emitted through the event bus with the `id`\n * included in the payload, allowing multiple map instances to coexist without interference.\n *\n * @param props - Component props including id (required), className, onClick, onHover, and all Deck.gl props\n * @returns A map component with Deck.gl and MapLibre GL integration\n *\n * @example\n * Basic usage with id (recommended: module-level constant):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { View } from '@deckgl-fiber-renderer/dom';\n * import { uuid } from '@accelint/core';\n *\n * // Create id at module level for stability and easy sharing\n * const MAIN_MAP_ID = uuid();\n *\n * export function MapView() {\n *   return (\n *     <BaseMap className=\"w-full h-full\" id={MAIN_MAP_ID}>\n *       <View id=\"main\" controller />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example\n * With map mode and event handlers (module-level constant for sharing):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { useMapMode } from '@accelint/map-toolkit/map-mode';\n * import { uuid } from '@accelint/core';\n * import type { PickingInfo } from '@deck.gl/core';\n * import type { MjolnirGestureEvent } from 'mjolnir.js';\n *\n * // Module-level constant - stable and shareable across all components\n * const MAIN_MAP_ID = uuid();\n *\n * function Toolbar() {\n *   // Access map mode using the shared id\n *   const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);\n *   return <div>Current mode: {mode}</div>;\n * }\n *\n * export function InteractiveMap() {\n *   const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {\n *     console.log('Clicked:', info.object);\n *   };\n *\n *   return (\n *     <div className=\"relative w-full h-full\">\n *       <BaseMap className=\"absolute inset-0\" id={MAIN_MAP_ID} onClick={handleClick}>\n *         <View id=\"main\" controller />\n *       </BaseMap>\n *       <Toolbar />\n *     </div>\n *   );\n * }\n * ```\n */\nexport function BaseMap({\n  id,\n  className,\n  children,\n  controller = true,\n  interleaved = true,\n  parameters = {},\n  useDevicePixels = false,\n  widgets: widgetsProp = [],\n  onClick,\n  onHover,\n  onViewStateChange,\n  ...rest\n}: BaseMapProps) {\n  const deckglInstance = useDeckgl();\n  const container = useId();\n\n  // Memoize MapLibre options to avoid creating new object on every render\n  const mapOptions = useMemo(\n    () => ({\n      container,\n      center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude] as [\n        number,\n        number,\n      ],\n      zoom: INITIAL_VIEW_STATE.zoom,\n      doubleClickZoom: false,\n      dragRotate: false,\n      pitchWithRotate: false,\n      rollEnabled: false,\n      attributionControl: { compact: true },\n    }),\n    [container],\n  );\n\n  // Use the custom hook to handle MapLibre\n  useMapLibre(deckglInstance as IControl, BASE_MAP_STYLE, mapOptions);\n\n  const emitClick = useEmit<MapClickEvent>(MapEvents.click);\n  const emitHover = useEmit<MapHoverEvent>(MapEvents.hover);\n  const emitViewport = useEmit<MapViewportEvent>(MapEvents.viewport);\n\n  const handleClick = useCallback(\n    (info: PickingInfo, event: MjolnirGestureEvent) => {\n      // send full pickingInfo and event to user-defined onClick\n      onClick?.(info, event);\n\n      emitClick({\n        info: serializePickingInfo(info),\n        event: serializeMjolnirEvent(event),\n        id,\n      });\n    },\n    [emitClick, id, onClick],\n  );\n\n  const handleHover = useCallback(\n    (info: PickingInfo, event: MjolnirPointerEvent) => {\n      // send full pickingInfo and event to user-defined onHover\n      onHover?.(info, event);\n\n      emitHover({\n        info: serializePickingInfo(info),\n        event: serializeMjolnirEvent(event),\n        id,\n      });\n    },\n    [emitHover, id, onHover],\n  );\n\n  const handleGetCursor = useCallback(() => {\n    return getCursor(id);\n  }, [id]);\n\n  const handleViewStateChange = useEffectEvent(\n    (params: ViewStateChangeParameters) => {\n      onViewStateChange?.(params);\n\n      const {\n        viewId,\n        viewState: { latitude, longitude, zoom },\n      } = params;\n\n      // @ts-expect-error squirrelly deckglInstance typing\n      const viewport = deckglInstance._deck\n        .getViewports()\n        // @ts-expect-error squirrelly deckglInstance typing\n        ?.find((vp) => vp.id === viewId);\n\n      emitViewport({\n        id,\n        bounds: viewport?.getBounds(),\n        latitude,\n        longitude,\n        zoom,\n        width: viewport?.width ?? 0,\n        height: viewport?.height ?? 0,\n      });\n    },\n  );\n\n  const handleLoad = useEffectEvent(() => {\n    //--- force update viewport state once all viewports initialized ---\n    // @ts-expect-error squirrelly deckglInstance typing\n    deckglInstance._deck.getViewports().forEach((vp) => {\n      handleViewStateChange({\n        viewId: vp.id,\n        viewState: {\n          latitude: vp.latitude,\n          longitude: vp.longitude,\n          zoom: vp.zoom,\n          id: vp.id,\n          bounds: vp.getBounds(),\n          width: vp.width,\n          height: vp.height,\n        },\n      } as ViewStateChangeParameters);\n    });\n  });\n\n  return (\n    <div id={container} className={className}>\n      <MapProvider id={id}>\n        <Deckgl\n          {...rest}\n          controller={controller}\n          interleaved={interleaved}\n          useDevicePixels={useDevicePixels}\n          onClick={handleClick}\n          onHover={handleHover}\n          onLoad={handleLoad}\n          onViewStateChange={handleViewStateChange}\n          getCursor={handleGetCursor}\n          // @ts-expect-error - DeckglProps parameters type is overly strict for WebGL parameter spreading.\n          // The merged object is valid at runtime but TypeScript cannot verify all possible parameter combinations.\n          parameters={{ ...PARAMETERS, ...parameters }}\n        >\n          {children}\n        </Deckgl>\n      </MapProvider>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAS,qBAAqB,MAA4C;CACxE,MAAM,EAAE,UAAU,OAAO,aAAa,GAAG,aAAa;AACtD,QAAO;EACL,SAAS,OAAO;EAChB,eAAe,aAAa;EAC5B,GAAG;EACJ;;AAmCH,SAAS,sBACP,OACA;CACA,MAAM,EACJ,0BACA,iBACA,gBACA,UACA,aACA,QACA,GAAG,SACD;AAGJ,KAAI,qBAAqB,MAAM;EAC7B,MAAM,EAAE,iBAAiB,UAAU,GAAG,gBAAgB;AACtD,SAAO;;AAGT,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+FT,SAAgB,QAAQ,EACtB,IACA,WACA,UACA,aAAa,MACb,cAAc,MACd,aAAa,EAAE,EACf,kBAAkB,OAClB,SAAS,cAAc,EAAE,EACzB,SACA,SACA,mBACA,GAAG,QACY;CACf,MAAM,iBAAiB,WAAW;CAClC,MAAM,YAAY,OAAO;AAqBzB,aAAY,gBAA4B,gBAlBrB,eACV;EACL;EACA,QAAQ,CAAC,mBAAmB,WAAW,mBAAmB,SAAS;EAInE,MAAM,mBAAmB;EACzB,iBAAiB;EACjB,YAAY;EACZ,iBAAiB;EACjB,aAAa;EACb,oBAAoB,EAAE,SAAS,MAAM;EACtC,GACD,CAAC,UAAU,CACZ,CAGkE;CAEnE,MAAM,YAAY,QAAuB,UAAU,MAAM;CACzD,MAAM,YAAY,QAAuB,UAAU,MAAM;CACzD,MAAM,eAAe,QAA0B,UAAU,SAAS;CAElE,MAAM,cAAc,aACjB,MAAmB,UAA+B;AAEjD,YAAU,MAAM,MAAM;AAEtB,YAAU;GACR,MAAM,qBAAqB,KAAK;GAChC,OAAO,sBAAsB,MAAM;GACnC;GACD,CAAC;IAEJ;EAAC;EAAW;EAAI;EAAQ,CACzB;CAED,MAAM,cAAc,aACjB,MAAmB,UAA+B;AAEjD,YAAU,MAAM,MAAM;AAEtB,YAAU;GACR,MAAM,qBAAqB,KAAK;GAChC,OAAO,sBAAsB,MAAM;GACnC;GACD,CAAC;IAEJ;EAAC;EAAW;EAAI;EAAQ,CACzB;CAED,MAAM,kBAAkB,kBAAkB;AACxC,SAAO,UAAU,GAAG;IACnB,CAAC,GAAG,CAAC;CAER,MAAM,wBAAwB,gBAC3B,WAAsC;AACrC,sBAAoB,OAAO;EAE3B,MAAM,EACJ,QACA,WAAW,EAAE,UAAU,WAAW,WAChC;EAGJ,MAAM,WAAW,eAAe,MAC7B,cAAc,EAEb,MAAM,OAAO,GAAG,OAAO,OAAO;AAElC,eAAa;GACX;GACA,QAAQ,UAAU,WAAW;GAC7B;GACA;GACA;GACA,OAAO,UAAU,SAAS;GAC1B,QAAQ,UAAU,UAAU;GAC7B,CAAC;GAEL;CAED,MAAM,aAAa,qBAAqB;AAGtC,iBAAe,MAAM,cAAc,CAAC,SAAS,OAAO;AAClD,yBAAsB;IACpB,QAAQ,GAAG;IACX,WAAW;KACT,UAAU,GAAG;KACb,WAAW,GAAG;KACd,MAAM,GAAG;KACT,IAAI,GAAG;KACP,QAAQ,GAAG,WAAW;KACtB,OAAO,GAAG;KACV,QAAQ,GAAG;KACZ;IACF,CAA8B;IAC/B;GACF;AAEF,QACE,oBAAC;EAAI,IAAI;EAAsB;YAC7B,oBAAC;GAAgB;aACf,oBAAC;IACC,GAAI;IACQ;IACC;IACI;IACjB,SAAS;IACT,SAAS;IACT,QAAQ;IACR,mBAAmB;IACnB,WAAW;IAGX,YAAY;KAAE,GAAG;KAAY,GAAG;KAAY;IAE3C;KACM;IACG;GACV"}
+{"version":3,"file":"index.js","names":["MapLibre"],"sources":["../../../src/deckgl/base-map/index.tsx"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n'use client';\n\nimport 'client-only';\nimport { useEffectEvent, useEmit } from '@accelint/bus/react';\nimport { Deckgl, useDeckgl } from '@deckgl-fiber-renderer/dom';\nimport { useCallback, useId, useMemo, useRef } from 'react';\nimport {\n  Map as MapLibre,\n  type MapRef,\n  useControl,\n  type ViewState,\n} from 'react-map-gl/maplibre';\nimport { useCameraState } from '../../camera';\nimport { getCursor } from '../../map-cursor/store';\nimport {\n  DARK_BASE_MAP_STYLE,\n  DEFAULT_VIEW_STATE,\n  PARAMETERS,\n  PICKING_RADIUS,\n} from './constants';\nimport { MapControls } from './controls';\nimport { MapEvents } from './events';\nimport { MapProvider } from './provider';\nimport type { PickingInfo, ViewStateChangeParameters } from '@deck.gl/core';\nimport type { IControl } from 'maplibre-gl';\nimport type { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';\nimport type {\n  BaseMapProps,\n  MapClickEvent,\n  MapHoverEvent,\n  MapViewportEvent,\n  SerializablePickingInfo,\n} from './types';\n\n/**\n * Serializes PickingInfo for event bus transmission.\n * Omits viewport, layer, and sourceLayer (contain functions) but preserves layer IDs.\n */\nfunction serializePickingInfo(info: PickingInfo): SerializablePickingInfo {\n  const { viewport, layer, sourceLayer, ...infoRest } = info;\n  return {\n    layerId: layer?.id,\n    sourceLayerId: sourceLayer?.id,\n    ...infoRest,\n  };\n}\n\n/**\n * Strips non-serializable properties from MjolnirGestureEvent for event bus transmission.\n * Removes functions, DOM elements, and PointerEvent objects that cannot be cloned.\n */\nfunction serializeMjolnirEvent(\n  event: MjolnirGestureEvent,\n): Omit<\n  MjolnirGestureEvent,\n  | 'stopPropagation'\n  | 'preventDefault'\n  | 'stopImmediatePropagation'\n  | 'srcEvent'\n  | 'rootElement'\n  | 'target'\n  | 'changedPointers'\n  | 'pointers'\n>;\n/**\n * Strips non-serializable properties from MjolnirPointerEvent for event bus transmission.\n * Removes functions and DOM elements that cannot be cloned.\n */\nfunction serializeMjolnirEvent(\n  event: MjolnirPointerEvent,\n): Omit<\n  MjolnirPointerEvent,\n  | 'stopPropagation'\n  | 'preventDefault'\n  | 'stopImmediatePropagation'\n  | 'srcEvent'\n  | 'rootElement'\n  | 'target'\n>;\nfunction serializeMjolnirEvent(\n  event: MjolnirGestureEvent | MjolnirPointerEvent,\n) {\n  const {\n    stopImmediatePropagation,\n    stopPropagation,\n    preventDefault,\n    srcEvent,\n    rootElement,\n    target,\n    ...rest\n  } = event;\n\n  // Remove pointer arrays if present (only on MjolnirGestureEvent)\n  if ('changedPointers' in rest) {\n    const { changedPointers, pointers, ...gestureRest } = rest;\n    return gestureRest;\n  }\n\n  return rest;\n}\n\nfunction AddDeckglControl() {\n  const deckglInstance = useDeckgl();\n  useControl(() => deckglInstance as IControl);\n\n  return null;\n}\n\n/**\n * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.\n *\n * This component serves as the foundation for building interactive map applications with\n * support for click and hover events through a centralized event bus. It integrates\n * Deck.gl for 3D visualizations with MapLibre GL for the base map tiles.\n *\n * **Map Mode Integration**: BaseMap automatically creates a `MapProvider` internally,\n * which sets up the map mode state management for this instance.\n * - **Children**: Only Deck.gl layer components can be rendered as children. Custom Deck.gl\n *   layers can use `useMapMode()` without parameters to access context.\n * - **Siblings**: UI components (buttons, toolbars, etc.) must be rendered as siblings\n *   and pass `id` to `useMapMode(id)`.\n *\n * **Event Bus**: Click and hover events are emitted through the event bus with the `id`\n * included in the payload, allowing multiple map instances to coexist without interference.\n *\n * @param props - Component props including id (required), className, onClick, onHover, and all Deck.gl props\n * @returns A map component with Deck.gl and MapLibre GL integration\n *\n * @example\n * Basic usage with id (recommended: module-level constant):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { View } from '@deckgl-fiber-renderer/dom';\n * import { uuid } from '@accelint/core';\n *\n * // Create id at module level for stability and easy sharing\n * const MAIN_MAP_ID = uuid();\n *\n * export function MapView() {\n *   return (\n *     <BaseMap className=\"w-full h-full\" id={MAIN_MAP_ID}>\n *       <View id=\"main\" controller />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example\n * With map mode and event handlers (module-level constant for sharing):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { useMapMode } from '@accelint/map-toolkit/map-mode';\n * import { uuid } from '@accelint/core';\n * import type { PickingInfo } from '@deck.gl/core';\n * import type { MjolnirGestureEvent } from 'mjolnir.js';\n *\n * // Module-level constant - stable and shareable across all components\n * const MAIN_MAP_ID = uuid();\n *\n * function Toolbar() {\n *   // Access map mode using the shared id\n *   const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);\n *   return <div>Current mode: {mode}</div>;\n * }\n *\n * export function InteractiveMap() {\n *   const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {\n *     console.log('Clicked:', info.object);\n *   };\n *\n *   return (\n *     <div className=\"relative w-full h-full\">\n *       <BaseMap className=\"absolute inset-0\" id={MAIN_MAP_ID} onClick={handleClick}>\n *         <View id=\"main\" controller />\n *       </BaseMap>\n *       <Toolbar />\n *     </div>\n *   );\n * }\n * ```\n */\nexport function BaseMap({\n  id,\n  className,\n  children,\n  controller = true,\n  enableControlEvents = true,\n  interleaved = true,\n  parameters = {},\n  styleUrl = DARK_BASE_MAP_STYLE,\n  useDevicePixels = false,\n  widgets: widgetsProp = [],\n  defaultView = '2D',\n  initialViewState,\n  onClick,\n  onHover,\n  onViewStateChange,\n  pickingRadius,\n  ...rest\n}: BaseMapProps) {\n  const deckglInstance = useDeckgl();\n  const container = useId();\n  const mapRef = useRef<MapRef>(null);\n\n  const { cameraState, setCameraState } = useCameraState({\n    instanceId: id,\n    initialCameraState: {\n      view: defaultView,\n      zoom: initialViewState?.zoom ?? DEFAULT_VIEW_STATE.zoom,\n      latitude: initialViewState?.latitude ?? DEFAULT_VIEW_STATE.latitude,\n      longitude: initialViewState?.longitude ?? DEFAULT_VIEW_STATE.longitude,\n    },\n  });\n\n  const viewState = useMemo<ViewState>(\n    () => ({\n      // @ts-expect-error squirrelly deckglInstance typing\n      ...(deckglInstance?._deck?._getViewState() as ViewState),\n      ...cameraState,\n      bearing: cameraState.rotation,\n    }),\n    // @ts-expect-error squirrelly deckglInstance typing\n    [cameraState, deckglInstance?._deck?._getViewState],\n  );\n\n  // Memoize MapLibre options to avoid creating new object on every render\n  const mapOptions = useMemo(\n    () => ({\n      container,\n      zoom: viewState.zoom,\n      pitch: viewState.pitch,\n      bearing: viewState.bearing,\n      latitude: viewState.latitude,\n      longitude: viewState.longitude,\n      doubleClickZoom: false,\n      dragRotate: false,\n      pitchWithRotate: false,\n      rollEnabled: false,\n      attributionControl: { compact: true },\n      projection: cameraState.projection,\n      maxPitch: cameraState.view === '2D' ? 0 : 85,\n    }),\n    [viewState, container, cameraState.projection, cameraState.view],\n  );\n\n  const emitClick = useEmit<MapClickEvent>(MapEvents.click);\n  const emitHover = useEmit<MapHoverEvent>(MapEvents.hover);\n  const emitViewport = useEmit<MapViewportEvent>(MapEvents.viewport);\n\n  const handleClick = useCallback(\n    (info: PickingInfo, event: MjolnirGestureEvent) => {\n      // send full pickingInfo and event to user-defined onClick\n      onClick?.(info, event);\n\n      emitClick({\n        info: serializePickingInfo(info),\n        event: serializeMjolnirEvent(event),\n        id,\n      });\n    },\n    [emitClick, id, onClick],\n  );\n\n  const handleHover = useCallback(\n    (info: PickingInfo, event: MjolnirPointerEvent) => {\n      // send full pickingInfo and event to user-defined onHover\n      onHover?.(info, event);\n\n      emitHover({\n        info: serializePickingInfo(info),\n        event: serializeMjolnirEvent(event),\n        id,\n      });\n    },\n    [emitHover, id, onHover],\n  );\n\n  const handleGetCursor = useCallback(() => {\n    return getCursor(id);\n  }, [id]);\n\n  const handleViewStateChange = useEffectEvent(\n    (params: ViewStateChangeParameters) => {\n      onViewStateChange?.(params);\n\n      const {\n        viewId,\n        viewState: { latitude, longitude, zoom },\n      } = params;\n\n      // @ts-expect-error squirrelly deckglInstance typing\n      const viewport = deckglInstance._deck\n        .getViewports()\n        // @ts-expect-error squirrelly deckglInstance typing\n        ?.find((vp) => vp.id === viewId);\n\n      emitViewport({\n        id,\n        bounds: viewport?.getBounds(),\n        latitude,\n        longitude,\n        zoom,\n        width: viewport?.width ?? 0,\n        height: viewport?.height ?? 0,\n      });\n    },\n  );\n\n  const handleLoad = useEffectEvent(() => {\n    //--- force update viewport state once all viewports initialized ---\n    // @ts-expect-error squirrelly deckglInstance typing\n    const viewports = deckglInstance._deck.getViewports() ?? [];\n    for (const vp of viewports) {\n      handleViewStateChange({\n        viewId: vp.id,\n        viewState: {\n          latitude: vp.latitude,\n          longitude: vp.longitude,\n          zoom: vp.zoom,\n          id: vp.id,\n          bounds: vp.getBounds(),\n          width: vp.width,\n          height: vp.height,\n        },\n      } as ViewStateChangeParameters);\n    }\n  });\n\n  return (\n    <div id={container} className={className}>\n      {enableControlEvents && <MapControls id={id} mapRef={mapRef} />}\n      <MapProvider id={id}>\n        <MapLibre\n          onMove={(evt) => setCameraState(id, evt.viewState)}\n          mapStyle={styleUrl}\n          ref={mapRef}\n          {...mapOptions}\n        >\n          <Deckgl\n            {...rest}\n            interleaved={interleaved}\n            getCursor={handleGetCursor}\n            useDevicePixels={useDevicePixels}\n            onClick={handleClick}\n            pickingRadius={pickingRadius ?? PICKING_RADIUS}\n            onHover={handleHover}\n            onLoad={handleLoad}\n            onViewStateChange={handleViewStateChange}\n            // @ts-expect-error - DeckglProps parameters type is overly strict for WebGL parameter spreading.\n            // The merged object is valid at runtime but TypeScript cannot verify all possible parameter combinations.\n            parameters={{ ...PARAMETERS, ...parameters }}\n          >\n            <AddDeckglControl />\n            {children}\n          </Deckgl>\n        </MapLibre>\n      </MapProvider>\n    </div>\n  );\n}\n"],"mappings":"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"}

package/dist/deckgl/base-map/types.d.ts

@@ -14,9 +14,43 @@ import { MapEvents } from "./events.js";
 import { Payload } from "@accelint/bus";
 import { UniqueId } from "@accelint/core";
 import { PickingInfo } from "@deck.gl/core";
+import { DeckglProps } from "@deckgl-fiber-renderer/types";
 import { MjolnirGestureEvent, MjolnirPointerEvent } from "mjolnir.js";
 
 //#region src/deckgl/base-map/types.d.ts
+/**
+ * Props for the BaseMap component.
+ * Extends all Deck.gl props and adds additional map-specific properties.
+ */
+type BaseMapProps = DeckglProps & {
+  /** Optional CSS class name to apply to the map container element */
+  className?: string;
+  /**
+   * Whether to enable listening for map control events (pan/zoom enable/disable).
+   * When true, the map will respond to control events emitted via the event bus.
+   * @default true
+   */
+  enableControlEvents?: boolean;
+  /**
+   * Unique identifier for this map instance (required).
+   *
+   * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).
+   * This should be a UUID generated using `uuid()` from `@accelint/core`.
+   *
+   * The same id should be passed to `useMapMode()` when accessing map mode state
+   * from components rendered outside of the BaseMap's children (i.e., as siblings).
+   */
+  id: UniqueId;
+  /**
+   * Default view for the map: '2D', '2.5D', or '3D'. Defaults to '2D'.
+   */
+  defaultView?: '2D' | '2.5D' | '3D';
+  /**
+   * MapLibre style URL for the base map tiles.
+   * @default DARK_BASE_MAP_STYLE ('https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json')
+   */
+  styleUrl?: string;
+};
 /**
  * PickingInfo modified for serialization through the event bus.
  * Omits viewport, layer, and sourceLayer (which contain non-serializable functions),
@@ -86,7 +120,19 @@ type MapClickEvent = Payload<typeof MapEvents.click, MapClickPayload>;
  */
 type MapHoverEvent = Payload<typeof MapEvents.hover, MapHoverPayload>;
 type MapViewportEvent = Payload<typeof MapEvents.viewport, MapViewportPayload>;
-type MapEventType = MapClickEvent | MapHoverEvent | MapViewportEvent;
+/**
+ * Payload for map control events that target a specific map instance.
+ * Used for enablePan, disablePan, enableZoom, disableZoom events.
+ */
+type MapControlPayload = {
+  /** The map instance to apply the control change to */
+  id: UniqueId;
+};
+type MapEnablePanEvent = Payload<typeof MapEvents.enablePan, MapControlPayload>;
+type MapDisablePanEvent = Payload<typeof MapEvents.disablePan, MapControlPayload>;
+type MapEnableZoomEvent = Payload<typeof MapEvents.enableZoom, MapControlPayload>;
+type MapDisableZoomEvent = Payload<typeof MapEvents.disableZoom, MapControlPayload>;
+type MapEventType = MapClickEvent | MapHoverEvent | MapViewportEvent | MapEnablePanEvent | MapDisablePanEvent | MapEnableZoomEvent | MapDisableZoomEvent;
 //#endregion
-export { Bounds, MapClickEvent, MapClickPayload, MapEventType, MapHoverEvent, MapHoverPayload, MapViewportEvent, MapViewportPayload, SerializablePickingInfo };
+export { BaseMapProps, Bounds, MapClickEvent, MapClickPayload, MapControlPayload, MapDisablePanEvent, MapDisableZoomEvent, MapEnablePanEvent, MapEnableZoomEvent, MapEventType, MapHoverEvent, MapHoverPayload, MapViewportEvent, MapViewportPayload, SerializablePickingInfo };
 //# sourceMappingURL=types.d.ts.map

package/dist/deckgl/index.d.ts

@@ -10,9 +10,16 @@
  * governing permissions and limitations under the License.
  */
 
-import { BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
 import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
-import { BaseMap, BaseMapProps } from "./base-map/index.js";
-import { MapClickEvent, MapClickPayload, MapEventType, MapHoverEvent, MapHoverPayload } from "./base-map/types.js";
+import { BaseMapProps, MapClickEvent, MapClickPayload, MapControlPayload, MapDisablePanEvent, MapDisableZoomEvent, MapEnablePanEvent, MapEnableZoomEvent, MapEventType, MapHoverEvent, MapHoverPayload } from "./base-map/types.js";
+import { DARK_BASE_MAP_STYLE, LIGHT_BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
+import { BaseMap } from "./base-map/index.js";
+import { SavedViewportOptions, createSavedViewport } from "./saved-viewports/index.js";
+import { CircleProperties, CircleRadius, DisplayShape, EditableShape, ShapeFeature, ShapeFeatureProperties, ShapeFeatureType, ShapeFeatureTypeValues, ShapeId, StyleProperties } from "./shapes/shared/types.js";
+import { DisplayShapeLayerProps, StyledFeature, StyledFeatureProperties } from "./shapes/display-shape-layer/types.js";
+import { DisplayShapeLayer } from "./shapes/display-shape-layer/index.js";
+import { DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS } from "./shapes/shared/constants.js";
+import { SHAPE_EVENTS, ShapeEventHandler, ShapeEventPayload, ShapeEventType, ShapeEvents } from "./shapes/shared/events.js";
+import "./shapes/index.js";
 import { SymbolLayer, SymbolLayerProps } from "./symbol-layer/index.js";
-export { BASE_MAP_STYLE, BaseMap, type BaseMapProps, type MapClickEvent, type MapClickPayload, type MapEventType, MapEvents, MapEventsNamespace, type MapHoverEvent, type MapHoverPayload, PARAMETERS, SymbolLayer, type SymbolLayerProps };
+export { BaseMap, type BaseMapProps, type CircleProperties, type CircleRadius, DARK_BASE_MAP_STYLE, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, type DisplayShape, DisplayShapeLayer, type DisplayShapeLayerProps, type EditableShape, LIGHT_BASE_MAP_STYLE, type MapClickEvent, type MapClickPayload, type MapControlPayload, type MapDisablePanEvent, type MapDisableZoomEvent, type MapEnablePanEvent, type MapEnableZoomEvent, type MapEventType, MapEvents, MapEventsNamespace, type MapHoverEvent, type MapHoverPayload, PARAMETERS, SHAPE_EVENTS, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS, type SavedViewportOptions, type ShapeEventHandler, type ShapeEventPayload, type ShapeEventType, ShapeEvents, type ShapeFeature, type ShapeFeatureProperties, ShapeFeatureType, type ShapeFeatureTypeValues, type ShapeId, type StyleProperties, type StyledFeature, type StyledFeatureProperties, SymbolLayer, type SymbolLayerProps, createSavedViewport };

package/dist/deckgl/index.js

@@ -12,8 +12,13 @@
 
 
 import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
-import { BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
+import { DARK_BASE_MAP_STYLE, LIGHT_BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
 import { BaseMap } from "./base-map/index.js";
+import { createSavedViewport } from "./saved-viewports/index.js";
+import { DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS } from "./shapes/shared/constants.js";
+import { SHAPE_EVENTS, ShapeEvents } from "./shapes/shared/events.js";
+import { DisplayShapeLayer } from "./shapes/display-shape-layer/index.js";
+import { ShapeFeatureType } from "./shapes/shared/types.js";
 import { SymbolLayer } from "./symbol-layer/index.js";
 
-export { BASE_MAP_STYLE, BaseMap, MapEvents, MapEventsNamespace, PARAMETERS, SymbolLayer };
+export { BaseMap, DARK_BASE_MAP_STYLE, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, LIGHT_BASE_MAP_STYLE, MapEvents, MapEventsNamespace, PARAMETERS, SHAPE_EVENTS, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS, ShapeEvents, ShapeFeatureType, SymbolLayer, createSavedViewport };

package/dist/deckgl/saved-viewports/index.d.ts

@@ -0,0 +1,32 @@
+/*
+ * 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 { HotkeyOptions, KeyCombinationId, registerHotkey } from "@accelint/hotkey-manager";
+import { MapViewState } from "@deck.gl/core";
+import { RequireAllOrNone } from "type-fest";
+
+//#region src/deckgl/saved-viewports/index.d.ts
+type BaseOptions = {
+  uniqueIdentifier?: string;
+  threshold?: number;
+  getCurrentViewport: () => MapViewState;
+  setCurrentViewport: (viewport: MapViewState) => void;
+};
+type PersistOptions = RequireAllOrNone<{
+  getSavedViewport: (id: KeyCombinationId, uniqueIdentifier?: string) => MapViewState;
+  setSavedViewport: (id: KeyCombinationId, viewport: MapViewState, uniqueIdentifier?: string) => void;
+}>;
+type SavedViewportOptions = Partial<HotkeyOptions> & BaseOptions & PersistOptions;
+declare const createSavedViewport: (options: SavedViewportOptions) => ReturnType<typeof registerHotkey>;
+//#endregion
+export { SavedViewportOptions, createSavedViewport };
+//# sourceMappingURL=index.d.ts.map

package/dist/deckgl/saved-viewports/index.js

@@ -0,0 +1,51 @@
+/*
+ * 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 { STORAGE_ID, persist, retrieve } from "./storage.js";
+import { Keycode, registerHotkey } from "@accelint/hotkey-manager";
+
+//#region src/deckgl/saved-viewports/index.ts
+const createSavedViewport = (options) => {
+	const setFn = options.setSavedViewport ?? persist;
+	const getFn = options.getSavedViewport ?? retrieve;
+	return registerHotkey({
+		id: STORAGE_ID,
+		heldThresholdMs: options.threshold,
+		key: options.key ?? [
+			{ code: Keycode.Digit0 },
+			{ code: Keycode.Digit1 },
+			{ code: Keycode.Digit2 },
+			{ code: Keycode.Digit3 },
+			{ code: Keycode.Digit4 },
+			{ code: Keycode.Digit5 },
+			{ code: Keycode.Digit6 },
+			{ code: Keycode.Digit7 },
+			{ code: Keycode.Digit8 },
+			{ code: Keycode.Digit9 }
+		],
+		onKeyHeld: (e, key) => {
+			e.preventDefault();
+			const viewport = options.getCurrentViewport();
+			setFn(key.id, viewport, options.uniqueIdentifier);
+		},
+		onKeyUp: (e, key) => {
+			e.preventDefault();
+			const viewport = getFn(key.id, options.uniqueIdentifier);
+			if (viewport) options.setCurrentViewport(viewport);
+		}
+	});
+};
+
+//#endregion
+export { createSavedViewport };
+//# sourceMappingURL=index.js.map

package/dist/deckgl/saved-viewports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/deckgl/saved-viewports/index.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 {\n  type HotkeyOptions,\n  type KeyCombination,\n  type KeyCombinationId,\n  Keycode,\n  registerHotkey,\n} from '@accelint/hotkey-manager';\nimport { persist, retrieve, STORAGE_ID } from './storage';\nimport type { MapViewState } from '@deck.gl/core';\nimport type { RequireAllOrNone } from 'type-fest';\n\ntype BaseOptions = {\n  uniqueIdentifier?: string;\n  threshold?: number;\n  getCurrentViewport: () => MapViewState;\n  setCurrentViewport: (viewport: MapViewState) => void;\n};\n\ntype PersistOptions = RequireAllOrNone<{\n  getSavedViewport: (\n    id: KeyCombinationId,\n    uniqueIdentifier?: string,\n  ) => MapViewState;\n  setSavedViewport: (\n    id: KeyCombinationId,\n    viewport: MapViewState,\n    uniqueIdentifier?: string,\n  ) => void;\n}>;\n\nexport type SavedViewportOptions = Partial<HotkeyOptions> &\n  BaseOptions &\n  PersistOptions;\n\nexport const createSavedViewport = (\n  options: SavedViewportOptions,\n): ReturnType<typeof registerHotkey> => {\n  const setFn = options.setSavedViewport ?? persist;\n  const getFn = options.getSavedViewport ?? retrieve;\n\n  return registerHotkey({\n    id: STORAGE_ID,\n    heldThresholdMs: options.threshold,\n    key: options.key ?? [\n      {\n        code: Keycode.Digit0,\n      },\n      {\n        code: Keycode.Digit1,\n      },\n      {\n        code: Keycode.Digit2,\n      },\n      {\n        code: Keycode.Digit3,\n      },\n      {\n        code: Keycode.Digit4,\n      },\n      {\n        code: Keycode.Digit5,\n      },\n      {\n        code: Keycode.Digit6,\n      },\n      {\n        code: Keycode.Digit7,\n      },\n      {\n        code: Keycode.Digit8,\n      },\n      {\n        code: Keycode.Digit9,\n      },\n    ],\n    onKeyHeld: (e: KeyboardEvent, key: KeyCombination) => {\n      e.preventDefault();\n      const viewport = options.getCurrentViewport();\n      setFn(key.id, viewport, options.uniqueIdentifier);\n    },\n    onKeyUp: (e: KeyboardEvent, key: KeyCombination) => {\n      e.preventDefault();\n      const viewport = getFn(key.id, options.uniqueIdentifier);\n      if (viewport) {\n        options.setCurrentViewport(viewport);\n      }\n    },\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AA8CA,MAAa,uBACX,YACsC;CACtC,MAAM,QAAQ,QAAQ,oBAAoB;CAC1C,MAAM,QAAQ,QAAQ,oBAAoB;AAE1C,QAAO,eAAe;EACpB,IAAI;EACJ,iBAAiB,QAAQ;EACzB,KAAK,QAAQ,OAAO;GAClB,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACD,EACE,MAAM,QAAQ,QACf;GACF;EACD,YAAY,GAAkB,QAAwB;AACpD,KAAE,gBAAgB;GAClB,MAAM,WAAW,QAAQ,oBAAoB;AAC7C,SAAM,IAAI,IAAI,UAAU,QAAQ,iBAAiB;;EAEnD,UAAU,GAAkB,QAAwB;AAClD,KAAE,gBAAgB;GAClB,MAAM,WAAW,MAAM,IAAI,IAAI,QAAQ,iBAAiB;AACxD,OAAI,SACF,SAAQ,mBAAmB,SAAS;;EAGzC,CAAC"}

package/dist/deckgl/saved-viewports/storage.d.ts

@@ -0,0 +1,21 @@
+/*
+ * 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 { MapViewState } from "@deck.gl/core";
+
+//#region src/deckgl/saved-viewports/storage.d.ts
+declare const STORAGE_ID = "deckgl-saved-viewports";
+declare const persist: (id: string, obj: MapViewState, uniqueIdentifier?: string) => void;
+declare const retrieve: (id: string, uniqueIdentifier?: string) => any;
+//#endregion
+export { STORAGE_ID, persist, retrieve };
+//# sourceMappingURL=storage.d.ts.map

package/dist/deckgl/saved-viewports/storage.js

@@ -0,0 +1,39 @@
+/*
+ * 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/deckgl/saved-viewports/storage.ts
+const STORAGE_ID = "deckgl-saved-viewports";
+const getContainerKey = (uniqueIdentifier) => uniqueIdentifier ? `${STORAGE_ID}-${uniqueIdentifier}` : STORAGE_ID;
+const getContainer = (containerKey) => {
+	try {
+		return JSON.parse(localStorage.getItem(containerKey) ?? "{}");
+	} catch {
+		console.warn(`Failed to parse storage container for key: ${containerKey}, returning empty container.`);
+		return {};
+	}
+};
+const persist = (id, obj, uniqueIdentifier) => {
+	const containerKey = getContainerKey(uniqueIdentifier);
+	const container = getContainer(containerKey);
+	container[id] = obj;
+	localStorage.setItem(containerKey, JSON.stringify(container));
+};
+const retrieve = (id, uniqueIdentifier) => {
+	const obj = getContainer(getContainerKey(uniqueIdentifier))[id];
+	if (!obj) console.warn(`Object with id: ${id} does not exist`);
+	return obj;
+};
+
+//#endregion
+export { STORAGE_ID, persist, retrieve };
+//# sourceMappingURL=storage.js.map

package/dist/deckgl/saved-viewports/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../../../src/deckgl/saved-viewports/storage.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 { MapViewState } from '@deck.gl/core';\n\nexport const STORAGE_ID = 'deckgl-saved-viewports';\n\nconst getContainerKey = (uniqueIdentifier?: string) =>\n  uniqueIdentifier ? `${STORAGE_ID}-${uniqueIdentifier}` : STORAGE_ID;\n\nconst getContainer = (containerKey: string) => {\n  try {\n    return JSON.parse(localStorage.getItem(containerKey) ?? '{}');\n  } catch {\n    console.warn(\n      `Failed to parse storage container for key: ${containerKey}, returning empty container.`,\n    );\n    return {};\n  }\n};\n\nexport const persist = (\n  id: string,\n  obj: MapViewState,\n  uniqueIdentifier?: string,\n) => {\n  const containerKey = getContainerKey(uniqueIdentifier);\n  const container = getContainer(containerKey);\n  container[id] = obj;\n  localStorage.setItem(containerKey, JSON.stringify(container));\n};\n\nexport const retrieve = (id: string, uniqueIdentifier?: string) => {\n  const containerKey = getContainerKey(uniqueIdentifier);\n  const container = getContainer(containerKey);\n  const obj = container[id];\n  if (!obj) {\n    console.warn(`Object with id: ${id} does not exist`);\n  }\n  return obj;\n};\n"],"mappings":";;;;;;;;;;;;;;AAcA,MAAa,aAAa;AAE1B,MAAM,mBAAmB,qBACvB,mBAAmB,GAAG,WAAW,GAAG,qBAAqB;AAE3D,MAAM,gBAAgB,iBAAyB;AAC7C,KAAI;AACF,SAAO,KAAK,MAAM,aAAa,QAAQ,aAAa,IAAI,KAAK;SACvD;AACN,UAAQ,KACN,8CAA8C,aAAa,8BAC5D;AACD,SAAO,EAAE;;;AAIb,MAAa,WACX,IACA,KACA,qBACG;CACH,MAAM,eAAe,gBAAgB,iBAAiB;CACtD,MAAM,YAAY,aAAa,aAAa;AAC5C,WAAU,MAAM;AAChB,cAAa,QAAQ,cAAc,KAAK,UAAU,UAAU,CAAC;;AAG/D,MAAa,YAAY,IAAY,qBAA8B;CAGjE,MAAM,MADY,aADG,gBAAgB,iBAAiB,CACV,CACtB;AACtB,KAAI,CAAC,IACH,SAAQ,KAAK,mBAAmB,GAAG,iBAAiB;AAEtD,QAAO"}

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

@@ -0,0 +1,44 @@
+//#region src/deckgl/shapes/display-shape-layer/constants.d.ts
+/**
+ * Map interaction constants
+ * Values derived from ngc2 for consistency
+ */
+declare const MAP_INTERACTION: {
+  readonly LINE_WIDTH_MIN_PIXELS: 1;
+  readonly ICON_SIZE: 38;
+  readonly ICON_HOVER_SIZE_INCREASE: 5;
+};
+/**
+ * Selection highlight configuration
+ */
+declare const SELECTION_HIGHLIGHT: {
+  readonly COLOR: [number, number, number, number];
+  readonly ICON_SIZE_INCREASE: 8;
+};
+/**
+ * Coffin corners configuration for Point selection/hover feedback
+ * Coffin corners are bracket-like corners that appear around points
+ */
+declare const COFFIN_CORNERS: {
+  /** Icon name for hover state (white corners with background fill) */
+  readonly HOVER_ICON: "coffin-corners-hover";
+  /** Icon name for selected state (blue corners, no fill) */
+  readonly SELECTED_ICON: "coffin-corners-selected";
+  /** Icon name for selected+hover state (blue corners with background fill) */
+  readonly SELECTED_HOVER_ICON: "coffin-corners-selected-hover";
+  /** Size of the coffin corners icon */
+  readonly SIZE: 38;
+};
+/**
+ * Default props for DisplayShapeLayer
+ */
+declare const DEFAULT_DISPLAY_PROPS: {
+  pickable: boolean;
+  showLabels: boolean;
+  showHighlight: boolean;
+  applyBaseOpacity: boolean;
+  highlightColor: [number, number, number, number];
+};
+//#endregion
+export { COFFIN_CORNERS, DEFAULT_DISPLAY_PROPS, MAP_INTERACTION, SELECTION_HIGHLIGHT };
+//# sourceMappingURL=constants.d.ts.map