npm - @accelint/map-toolkit - Versions diffs - 1.1.0 → 1.3.0 - Mend

@accelint/map-toolkit 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (128) hide show

package/dist/cursor-coordinates/use-cursor-coordinates.js CHANGED Viewed

@@ -13,6 +13,7 @@
 'use client';
+import { DEFAULT_LATLON_COORDS, DEFAULT_MGRS_UTM_COORDS, LONGITUDE_RANGE, MAX_LONGITUDE } from "./constants.js";
 import { cursorCoordinateStore } from "./store.js";
 import { MapContext } from "../deckgl/base-map/provider.js";
 import { useContext, useMemo } from "react";
@@ -26,9 +27,6 @@ const logger = getLogger({
 	prefix: "[CursorCoordinates]",
 	pretty: true
 });
-const MAX_LONGITUDE = 180;
-const LONGITUDE_RANGE = 360;
-const DEFAULT_COORDINATE = "--, --";
 /**
 * Normalizes longitude to -180 to 180 range.
 * Handles wraparound including multi-revolution values.
@@ -62,6 +60,11 @@ function buildRawCoordinate(coord) {
 * @param coord - Coordinate tuple [longitude, latitude]
 * @param format - Coordinate format type
 * @returns Formatted coordinate string
+*  *
+* @remarks
+* **UTM/MGRS Limitations:** UTM and MGRS coordinate systems are only valid between 80°S and 84°N.
+* Coordinates outside this range (e.g., polar regions) will return the default placeholder `--, --`.
+* Other formats (DD, DDM, DMS) work correctly at all latitudes.
 */
 function formatCoordinate(coord, format) {
 	const normalizedLon = normalizeLongitude(coord[0]);
@@ -89,10 +92,16 @@ function formatCoordinate(coord, format) {
 		case "utm": {
 			const lat = latLon[0];
 			const lon = latLon[1];
+			if (lat < -80 || lat > 84) return DEFAULT_MGRS_UTM_COORDS;
 			const latOrdinal = lat >= 0 ? "N" : "S";
 			const lonOrdinal = lon >= 0 ? "E" : "W";
 			const formattedInput = `${Math.abs(lon).toFixed(10)} ${lonOrdinal} / ${Math.abs(lat).toFixed(10)} ${latOrdinal}`;
-			return createCoordinate(coordinateSystems.dd, "LONLAT")(formattedInput)[format]();
+			const geoCoord = createCoordinate(coordinateSystems.dd, "LONLAT")(formattedInput);
+			if (!geoCoord.valid) {
+				logger.error(`Failed to create coordinate for ${format}: ${geoCoord.errors.join(", ")}`);
+				return DEFAULT_MGRS_UTM_COORDS;
+			}
+			return geoCoord[format]();
 		}
 	}
 }
@@ -110,6 +119,11 @@ function formatCoordinate(coord, format) {
 * @returns Object containing the formatted coordinate string, raw coordinate, format setter, and current format
 * @throws {Error} When no id is provided and hook is used outside MapProvider context
 *
+* @remarks
+* **UTM/MGRS Limitations:** UTM and MGRS coordinate systems are only valid between 80°S and 84°N.
+* Coordinates outside this range (e.g., polar regions) will display the default placeholder `--, --`.
+* Other formats (DD, DDM, DMS) work correctly at all latitudes.
+*
 * @example
 * Basic usage:
 * ```tsx
@@ -177,12 +191,13 @@ function useCursorCoordinates(id, options) {
 	const { state, setFormat } = cursorCoordinateStore.use(actualId);
 	const rawCoord = useMemo(() => buildRawCoordinate(state.coordinate), [state.coordinate]);
 	const formattedCoord = useMemo(() => {
-		if (!rawCoord) return DEFAULT_COORDINATE;
+		const getDefaultCoords = () => state.format === "mgrs" || state.format === "utm" ? DEFAULT_MGRS_UTM_COORDS : DEFAULT_LATLON_COORDS;
+		if (!(rawCoord && state.coordinate)) return getDefaultCoords();
 		if (customFormatter) try {
 			return customFormatter(rawCoord);
 		} catch (error) {
 			logger.error(`Custom formatter failed: ${error instanceof Error ? error.message : String(error)}`);
-			return DEFAULT_COORDINATE;
+			return getDefaultCoords();
 		}
 		return formatCoordinate(state.coordinate, state.format);
 	}, [

package/dist/cursor-coordinates/use-cursor-coordinates.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"use-cursor-coordinates.js","names":["latLon: [number, number]"],"sources":["../../src/cursor-coordinates/use-cursor-coordinates.ts"],"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'use client';\n\nimport 'client-only';\nimport {\n coordinateSystems,\n createCoordinate,\n formatDecimalDegrees,\n formatDegreesDecimalMinutes,\n formatDegreesMinutesSeconds,\n} from '@accelint/geo';\nimport { getLogger } from '@accelint/logger';\nimport { useContext, useMemo } from 'react';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport { cursorCoordinateStore } from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type {\n CoordinateFormatTypes,\n RawCoordinate,\n UseCursorCoordinatesOptions,\n UseCursorCoordinatesReturn,\n} from './types';\n\nconst logger = getLogger({\n enabled:\n process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n level: 'warn',\n prefix: '[CursorCoordinates]',\n pretty: true,\n});\n\nconst MAX_LONGITUDE = 180;\nconst LONGITUDE_RANGE = 360;\nconst DEFAULT_COORDINATE = '--, --';\n\n/\n Normalizes longitude to -180 to 180 range.\n * Handles wraparound including multi-revolution values.\n \n @param lon - Longitude value in degrees\n * @returns Normalized longitude between -180 and 180\n /\nfunction normalizeLongitude(lon: number): number {\n return (\n ((((lon + MAX_LONGITUDE) % LONGITUDE_RANGE) + LONGITUDE_RANGE) %\n LONGITUDE_RANGE) -\n MAX_LONGITUDE\n );\n}\n\n/\n Builds a RawCoordinate object from a coordinate tuple.\n \n @param coord - Coordinate tuple [longitude, latitude] or null\n * @returns RawCoordinate object or null\n /\nfunction buildRawCoordinate(coord: [number, number] \| null): RawCoordinate {\n if (!coord) {\n return null;\n }\n\n const normalizedLon = normalizeLongitude(coord[0]);\n\n return {\n longitude: normalizedLon,\n latitude: coord[1],\n };\n}\n\n/\n Formats a coordinate using the specified format.\n * Uses @accelint/geo formatters which match CoordinateField precision:\n * - DD: 6 decimal places\n * - DDM: 4 decimal places for minutes\n * - DMS: 2 decimal places for seconds\n \n @param coord - Coordinate tuple [longitude, latitude]\n * @param format - Coordinate format type\n * @returns Formatted coordinate string\n /\nfunction formatCoordinate(\n coord: [number, number],\n format: CoordinateFormatTypes,\n): string {\n // Normalize longitude and convert to [lat, lon] for geo formatters\n const normalizedLon = normalizeLongitude(coord[0]);\n const latLon: [number, number] = [coord[1], normalizedLon];\n\n switch (format) {\n case 'dd':\n return formatDecimalDegrees(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'ddm':\n return formatDegreesDecimalMinutes(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'dms':\n return formatDegreesMinutesSeconds(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'mgrs':\n case 'utm': {\n // Use createCoordinate for grid-based formats\n // Input format: \"lon E / lat N\" for LONLAT (matching geo package DD tests)\n // Limit to 10 decimal places (geo parser max) and avoid floating point precision issues\n const lat = latLon[0];\n const lon = latLon[1];\n const latOrdinal = lat >= 0 ? 'N' : 'S';\n const lonOrdinal = lon >= 0 ? 'E' : 'W';\n // Use LONLAT format: longitude first, then latitude\n // toFixed(10) ensures we stay within the parser's regex limits\n const formattedInput = `${Math.abs(lon).toFixed(10)} ${lonOrdinal} / ${Math.abs(lat).toFixed(10)} ${latOrdinal}`;\n\n const geoCoord = createCoordinate(\n coordinateSystems.dd,\n 'LONLAT',\n )(formattedInput);\n\n return geoCoord[format]();\n }\n }\n}\n\n/\n React hook that tracks and formats the cursor hover position coordinates on a map.\n \n Subscribes to map hover events via the event bus and converts coordinates to various\n * geographic formats (Decimal Degrees, DMS, MGRS, UTM, etc.). The hook automatically\n * filters events to only process those from the specified map instance.\n \n Uses the shared store factory for efficient state management and automatic cleanup.\n \n @param id - Optional map instance ID. If not provided, attempts to use the ID from MapProvider context.\n * @param options - Optional configuration options\n * @returns Object containing the formatted coordinate string, raw coordinate, format setter, and current format\n * @throws {Error} When no id is provided and hook is used outside MapProvider context\n \n @example\n * Basic usage:\n * ```tsx\n * import { uuid } from '@accelint/core';\n * import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';\n \n const MAP_ID = uuid();\n \n function CoordinateDisplay() {\n * const { formattedCoord, setFormat } = useCursorCoordinates(MAP_ID);\n \n return (\n * <div>\n * <select onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}>\n * <option value=\"dd\">Decimal Degrees</option>\n * <option value=\"ddm\">Degrees Decimal Minutes</option>\n * <option value=\"dms\">Degrees Minutes Seconds</option>\n * <option value=\"mgrs\">MGRS</option>\n * <option value=\"utm\">UTM</option>\n * </select>\n * <div>{formattedCoord}</div>\n * </div>\n * );\n * }\n * ```\n \n @example\n * With custom formatter:\n * ```tsx\n * function CustomCoordinateDisplay() {\n * const { formattedCoord, rawCoord } = useCursorCoordinates(MAP_ID, {\n * formatter: (coord) =>\n * `Lat: ${coord.latitude.toFixed(6)}° Lng: ${coord.longitude.toFixed(6)}°`,\n * });\n \n return <div>{formattedCoord}</div>;\n * }\n * ```\n \n @example\n * Accessing raw coordinates:\n * ```tsx\n * function RawCoordinateDisplay() {\n * const { rawCoord, currentFormat } = useCursorCoordinates(MAP_ID);\n \n if (!rawCoord) {\n * return <div>Move cursor over map</div>;\n * }\n \n return (\n * <div>\n * <div>Longitude: {rawCoord.longitude}</div>\n * <div>Latitude: {rawCoord.latitude}</div>\n * <div>Format: {currentFormat}</div>\n * </div>\n * );\n * }\n * ```\n */\nexport function useCursorCoordinates(\n id?: UniqueId,\n options?: UseCursorCoordinatesOptions,\n): UseCursorCoordinatesReturn {\n const contextId = useContext(MapContext);\n const actualId = id ?? contextId;\n\n if (!actualId) {\n throw new Error(\n 'useCursorCoordinates requires either an id parameter or to be used within a MapProvider',\n );\n }\n\n const customFormatter = options?.formatter;\n\n // Use the store hook to get state and actions\n const { state, setFormat } = cursorCoordinateStore.use(actualId);\n\n // Build raw coordinate object\n const rawCoord = useMemo(\n () => buildRawCoordinate(state.coordinate),\n [state.coordinate],\n );\n\n // Compute formatted coordinate string\n const formattedCoord = useMemo(() => {\n if (!rawCoord) {\n return DEFAULT_COORDINATE;\n }\n\n // Use custom formatter if provided\n if (customFormatter) {\n try {\n return customFormatter(rawCoord);\n } catch (error) {\n logger.error(\n `Custom formatter failed: ${error instanceof Error ? error.message : String(error)}`,\n );\n return DEFAULT_COORDINATE;\n }\n }\n\n // Use built-in formatter\n return formatCoordinate(state.coordinate!, state.format);\n }, [rawCoord, customFormatter, state.format, state.coordinate]);\n\n // Memoize the return value to prevent unnecessary re-renders\n return useMemo(\n () => ({\n formattedCoord,\n setFormat,\n rawCoord,\n currentFormat: state.format,\n }),\n [formattedCoord, setFormat, rawCoord, state.format],\n );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAiCA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;AAEF,MAAM,gBAAgB;AACtB,MAAM,kBAAkB;AACxB,MAAM,qBAAqB;;;;;;;;AAS3B,SAAS,mBAAmB,KAAqB;AAC/C,UACM,MAAM,iBAAiB,kBAAmB,mBAC5C,kBACF;;;;;;;;AAUJ,SAAS,mBAAmB,OAA+C;AACzE,KAAI,CAAC,MACH,QAAO;AAKT,QAAO;EACL,WAHoB,mBAAmB,MAAM,GAAG;EAIhD,UAAU,MAAM;EACjB;;;;;;;;;;;;;AAcH,SAAS,iBACP,OACA,QACQ;CAER,MAAM,gBAAgB,mBAAmB,MAAM,GAAG;CAClD,MAAMA,SAA2B,CAAC,MAAM,IAAI,cAAc;AAE1D,SAAQ,QAAR;EACE,KAAK,KACH,QAAO,qBAAqB,QAAQ;GAClC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK,MACH,QAAO,4BAA4B,QAAQ;GACzC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK,MACH,QAAO,4BAA4B,QAAQ;GACzC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK;EACL,KAAK,OAAO;GAIV,MAAM,MAAM,OAAO;GACnB,MAAM,MAAM,OAAO;GACnB,MAAM,aAAa,OAAO,IAAI,MAAM;GACpC,MAAM,aAAa,OAAO,IAAI,MAAM;GAGpC,MAAM,iBAAiB,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,WAAW,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG;AAOpG,UALiB,iBACf,kBAAkB,IAClB,SACD,CAAC,eAAe,CAED,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8E/B,SAAgB,qBACd,IACA,SAC4B;CAC5B,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,0FACD;CAGH,MAAM,kBAAkB,SAAS;CAGjC,MAAM,EAAE,OAAO,cAAc,sBAAsB,IAAI,SAAS;CAGhE,MAAM,WAAW,cACT,mBAAmB,MAAM,WAAW,EAC1C,CAAC,MAAM,WAAW,CACnB;CAGD,MAAM,iBAAiB,cAAc;AACnC,MAAI,CAAC,SACH,QAAO;AAIT,MAAI,gBACF,KAAI;AACF,UAAO,gBAAgB,SAAS;WACzB,OAAO;AACd,UAAO,MACL,4BAA4B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GACnF;AACD,UAAO;;AAKX,SAAO,iBAAiB,MAAM,YAAa,MAAM,OAAO;IACvD;EAAC;EAAU;EAAiB,MAAM;EAAQ,MAAM;EAAW,CAAC;AAG/D,QAAO,eACE;EACL;EACA;EACA;EACA,eAAe,MAAM;EACtB,GACD;EAAC;EAAgB;EAAW;EAAU,MAAM;EAAO,CACpD"}
1	+ {"version":3,"file":"use-cursor-coordinates.js","names":["latLon: [number, number]"],"sources":["../../src/cursor-coordinates/use-cursor-coordinates.ts"],"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'use client';\n\nimport type { UniqueId } from '@accelint/core';\nimport {\n coordinateSystems,\n createCoordinate,\n formatDecimalDegrees,\n formatDegreesDecimalMinutes,\n formatDegreesMinutesSeconds,\n} from '@accelint/geo';\nimport { getLogger } from '@accelint/logger';\nimport 'client-only';\nimport { useContext, useMemo } from 'react';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport {\n DEFAULT_LATLON_COORDS,\n DEFAULT_MGRS_UTM_COORDS,\n LONGITUDE_RANGE,\n MAX_LONGITUDE,\n} from './constants';\nimport { cursorCoordinateStore } from './store';\nimport type {\n CoordinateFormatTypes,\n RawCoordinate,\n UseCursorCoordinatesOptions,\n UseCursorCoordinatesReturn,\n} from './types';\n\nconst logger = getLogger({\n enabled:\n process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n level: 'warn',\n prefix: '[CursorCoordinates]',\n pretty: true,\n});\n\n/\n Normalizes longitude to -180 to 180 range.\n * Handles wraparound including multi-revolution values.\n \n @param lon - Longitude value in degrees\n * @returns Normalized longitude between -180 and 180\n /\nfunction normalizeLongitude(lon: number): number {\n return (\n ((((lon + MAX_LONGITUDE) % LONGITUDE_RANGE) + LONGITUDE_RANGE) %\n LONGITUDE_RANGE) -\n MAX_LONGITUDE\n );\n}\n\n/\n Builds a RawCoordinate object from a coordinate tuple.\n \n @param coord - Coordinate tuple [longitude, latitude] or null\n * @returns RawCoordinate object or null\n /\nfunction buildRawCoordinate(coord: [number, number] \| null): RawCoordinate {\n if (!coord) {\n return null;\n }\n\n const normalizedLon = normalizeLongitude(coord[0]);\n\n return {\n longitude: normalizedLon,\n latitude: coord[1],\n };\n}\n\n/\n Formats a coordinate using the specified format.\n * Uses @accelint/geo formatters which match CoordinateField precision:\n * - DD: 6 decimal places\n * - DDM: 4 decimal places for minutes\n * - DMS: 2 decimal places for seconds\n \n @param coord - Coordinate tuple [longitude, latitude]\n * @param format - Coordinate format type\n * @returns Formatted coordinate string\n * \n @remarks\n * UTM/MGRS Limitations: UTM and MGRS coordinate systems are only valid between 80°S and 84°N.\n * Coordinates outside this range (e.g., polar regions) will return the default placeholder `--, --`.\n * Other formats (DD, DDM, DMS) work correctly at all latitudes.\n /\nfunction formatCoordinate(\n coord: [number, number],\n format: CoordinateFormatTypes,\n): string {\n // Normalize longitude and convert to [lat, lon] for geo formatters\n const normalizedLon = normalizeLongitude(coord[0]);\n const latLon: [number, number] = [coord[1], normalizedLon];\n\n switch (format) {\n case 'dd':\n return formatDecimalDegrees(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'ddm':\n return formatDegreesDecimalMinutes(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'dms':\n return formatDegreesMinutesSeconds(latLon, {\n withOrdinal: true,\n separator: ' / ',\n prefix: '',\n suffix: '',\n });\n case 'mgrs':\n case 'utm': {\n // UTM and MGRS are only valid between 80°S and 84°N\n // Use createCoordinate for grid-based formats\n // Input format: \"lon E / lat N\" for LONLAT (matching geo package DD tests)\n // Limit to 10 decimal places (geo parser max) and avoid floating point precision issues\n const lat = latLon[0];\n const lon = latLon[1];\n\n // Check if coordinate is within valid UTM/MGRS range\n if (lat < -80 \|\| lat > 84) {\n return DEFAULT_MGRS_UTM_COORDS;\n }\n\n const latOrdinal = lat >= 0 ? 'N' : 'S';\n const lonOrdinal = lon >= 0 ? 'E' : 'W';\n // Use LONLAT format: longitude first, then latitude\n // toFixed(10) ensures we stay within the parser's regex limits\n const formattedInput = `${Math.abs(lon).toFixed(10)} ${lonOrdinal} / ${Math.abs(lat).toFixed(10)} ${latOrdinal}`;\n\n const geoCoord = createCoordinate(\n coordinateSystems.dd,\n 'LONLAT',\n )(formattedInput);\n\n // Validate the coordinate was created successfully\n if (!geoCoord.valid) {\n logger.error(\n `Failed to create coordinate for ${format}: ${geoCoord.errors.join(', ')}`,\n );\n return DEFAULT_MGRS_UTM_COORDS;\n }\n\n return geoCoord[format]();\n }\n }\n}\n\n/\n React hook that tracks and formats the cursor hover position coordinates on a map.\n \n Subscribes to map hover events via the event bus and converts coordinates to various\n * geographic formats (Decimal Degrees, DMS, MGRS, UTM, etc.). The hook automatically\n * filters events to only process those from the specified map instance.\n \n Uses the shared store factory for efficient state management and automatic cleanup.\n \n @param id - Optional map instance ID. If not provided, attempts to use the ID from MapProvider context.\n * @param options - Optional configuration options\n * @returns Object containing the formatted coordinate string, raw coordinate, format setter, and current format\n * @throws {Error} When no id is provided and hook is used outside MapProvider context\n \n @remarks\n * UTM/MGRS Limitations: UTM and MGRS coordinate systems are only valid between 80°S and 84°N.\n * Coordinates outside this range (e.g., polar regions) will display the default placeholder `--, --`.\n * Other formats (DD, DDM, DMS) work correctly at all latitudes.\n \n @example\n * Basic usage:\n * ```tsx\n * import { uuid } from '@accelint/core';\n * import { useCursorCoordinates } from '@accelint/map-toolkit/cursor-coordinates';\n \n const MAP_ID = uuid();\n \n function CoordinateDisplay() {\n * const { formattedCoord, setFormat } = useCursorCoordinates(MAP_ID);\n \n return (\n * <div>\n * <select onChange={(e) => setFormat(e.target.value as CoordinateFormatTypes)}>\n * <option value=\"dd\">Decimal Degrees</option>\n * <option value=\"ddm\">Degrees Decimal Minutes</option>\n * <option value=\"dms\">Degrees Minutes Seconds</option>\n * <option value=\"mgrs\">MGRS</option>\n * <option value=\"utm\">UTM</option>\n * </select>\n * <div>{formattedCoord}</div>\n * </div>\n * );\n * }\n * ```\n \n @example\n * With custom formatter:\n * ```tsx\n * function CustomCoordinateDisplay() {\n * const { formattedCoord, rawCoord } = useCursorCoordinates(MAP_ID, {\n * formatter: (coord) =>\n * `Lat: ${coord.latitude.toFixed(6)}° Lng: ${coord.longitude.toFixed(6)}°`,\n * });\n \n return <div>{formattedCoord}</div>;\n * }\n * ```\n \n @example\n * Accessing raw coordinates:\n * ```tsx\n * function RawCoordinateDisplay() {\n * const { rawCoord, currentFormat } = useCursorCoordinates(MAP_ID);\n \n if (!rawCoord) {\n * return <div>Move cursor over map</div>;\n * }\n \n return (\n * <div>\n * <div>Longitude: {rawCoord.longitude}</div>\n * <div>Latitude: {rawCoord.latitude}</div>\n * <div>Format: {currentFormat}</div>\n * </div>\n * );\n * }\n * ```\n */\nexport function useCursorCoordinates(\n id?: UniqueId,\n options?: UseCursorCoordinatesOptions,\n): UseCursorCoordinatesReturn {\n const contextId = useContext(MapContext);\n const actualId = id ?? contextId;\n\n if (!actualId) {\n throw new Error(\n 'useCursorCoordinates requires either an id parameter or to be used within a MapProvider',\n );\n }\n\n const customFormatter = options?.formatter;\n\n // Use the store hook to get state and actions\n const { state, setFormat } = cursorCoordinateStore.use(actualId);\n\n // Build raw coordinate object\n const rawCoord = useMemo(\n () => buildRawCoordinate(state.coordinate),\n [state.coordinate],\n );\n\n // Compute formatted coordinate string\n const formattedCoord = useMemo(() => {\n // Return default coords based on current format.\n const getDefaultCoords = () =>\n state.format === 'mgrs' \|\| state.format === 'utm'\n ? DEFAULT_MGRS_UTM_COORDS\n : DEFAULT_LATLON_COORDS;\n\n if (!(rawCoord && state.coordinate)) {\n return getDefaultCoords();\n }\n\n // Use custom formatter if provided\n if (customFormatter) {\n try {\n return customFormatter(rawCoord);\n } catch (error) {\n logger.error(\n `Custom formatter failed: ${error instanceof Error ? error.message : String(error)}`,\n );\n return getDefaultCoords();\n }\n }\n\n // Use built-in formatter\n return formatCoordinate(state.coordinate, state.format);\n }, [rawCoord, customFormatter, state.format, state.coordinate]);\n\n // Memoize the return value to prevent unnecessary re-renders\n return useMemo(\n () => ({\n formattedCoord,\n setFormat,\n rawCoord,\n currentFormat: state.format,\n }),\n [formattedCoord, setFormat, rawCoord, state.format],\n );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;;;;;;;;AASF,SAAS,mBAAmB,KAAqB;AAC/C,UACM,MAAM,iBAAiB,kBAAmB,mBAC5C,kBACF;;;;;;;;AAUJ,SAAS,mBAAmB,OAA+C;AACzE,KAAI,CAAC,MACH,QAAO;AAKT,QAAO;EACL,WAHoB,mBAAmB,MAAM,GAAG;EAIhD,UAAU,MAAM;EACjB;;;;;;;;;;;;;;;;;;AAmBH,SAAS,iBACP,OACA,QACQ;CAER,MAAM,gBAAgB,mBAAmB,MAAM,GAAG;CAClD,MAAMA,SAA2B,CAAC,MAAM,IAAI,cAAc;AAE1D,SAAQ,QAAR;EACE,KAAK,KACH,QAAO,qBAAqB,QAAQ;GAClC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK,MACH,QAAO,4BAA4B,QAAQ;GACzC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK,MACH,QAAO,4BAA4B,QAAQ;GACzC,aAAa;GACb,WAAW;GACX,QAAQ;GACR,QAAQ;GACT,CAAC;EACJ,KAAK;EACL,KAAK,OAAO;GAKV,MAAM,MAAM,OAAO;GACnB,MAAM,MAAM,OAAO;AAGnB,OAAI,MAAM,OAAO,MAAM,GACrB,QAAO;GAGT,MAAM,aAAa,OAAO,IAAI,MAAM;GACpC,MAAM,aAAa,OAAO,IAAI,MAAM;GAGpC,MAAM,iBAAiB,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,WAAW,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG;GAEpG,MAAM,WAAW,iBACf,kBAAkB,IAClB,SACD,CAAC,eAAe;AAGjB,OAAI,CAAC,SAAS,OAAO;AACnB,WAAO,MACL,mCAAmC,OAAO,IAAI,SAAS,OAAO,KAAK,KAAK,GACzE;AACD,WAAO;;AAGT,UAAO,SAAS,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmF/B,SAAgB,qBACd,IACA,SAC4B;CAC5B,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,0FACD;CAGH,MAAM,kBAAkB,SAAS;CAGjC,MAAM,EAAE,OAAO,cAAc,sBAAsB,IAAI,SAAS;CAGhE,MAAM,WAAW,cACT,mBAAmB,MAAM,WAAW,EAC1C,CAAC,MAAM,WAAW,CACnB;CAGD,MAAM,iBAAiB,cAAc;EAEnC,MAAM,yBACJ,MAAM,WAAW,UAAU,MAAM,WAAW,QACxC,0BACA;AAEN,MAAI,EAAE,YAAY,MAAM,YACtB,QAAO,kBAAkB;AAI3B,MAAI,gBACF,KAAI;AACF,UAAO,gBAAgB,SAAS;WACzB,OAAO;AACd,UAAO,MACL,4BAA4B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GACnF;AACD,UAAO,kBAAkB;;AAK7B,SAAO,iBAAiB,MAAM,YAAY,MAAM,OAAO;IACtD;EAAC;EAAU;EAAiB,MAAM;EAAQ,MAAM;EAAW,CAAC;AAG/D,QAAO,eACE;EACL;EACA;EACA;EACA,eAAe,MAAM;EACtB,GACD;EAAC;EAAgB;EAAW;EAAU,MAAM;EAAO,CACpD"}

package/dist/deckgl/base-map/constants.d.ts CHANGED Viewed

@@ -1,5 +1,13 @@
 //#region src/deckgl/base-map/constants.d.ts
+/**
+ * Dark theme base map style URL from Carto.
+ * Provides a dark background for visualization layers.
+ */
 declare const DARK_BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+/**
+ * Light theme base map style URL from Carto.
+ * Provides a light background for visualization layers.
+ */
 declare const LIGHT_BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/voyager-gl-style/style.json";
 /**
  * Default picking radius in pixels
@@ -7,6 +15,10 @@ declare const LIGHT_BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/voy
  * Makes thin lines and small shapes easier to hover
  */
 declare const PICKING_RADIUS = 5;
+/**
+ * Default WebGL rendering parameters for Deck.gl.
+ * Configures depth testing, blending, and rendering behavior for optimal layer compositing.
+ */
 declare const PARAMETERS: {
   depthWriteEnabled: boolean;
   depthCompare: string;

package/dist/deckgl/base-map/constants.js CHANGED Viewed

@@ -12,7 +12,15 @@
 //#region src/deckgl/base-map/constants.ts
+/**
+* Dark theme base map style URL from Carto.
+* Provides a dark background for visualization layers.
+*/
 const DARK_BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+/**
+* Light theme base map style URL from Carto.
+* Provides a light background for visualization layers.
+*/
 const LIGHT_BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/voyager-gl-style/style.json";
 /**
 * Default picking radius in pixels
@@ -20,6 +28,10 @@ const LIGHT_BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/voyager-gl-
 * Makes thin lines and small shapes easier to hover
 */
 const PICKING_RADIUS = 5;
+/**
+* Default WebGL rendering parameters for Deck.gl.
+* Configures depth testing, blending, and rendering behavior for optimal layer compositing.
+*/
 const PARAMETERS = {
 	depthWriteEnabled: true,
 	depthCompare: "always",

package/dist/deckgl/base-map/constants.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"constants.js","names":[],"sources":["../../../src/deckgl/base-map/constants.ts"],"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\nexport const DARK_BASE_MAP_STYLE =\n 'https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json';\n\nexport const LIGHT_BASE_MAP_STYLE =\n 'https://tiles.basemaps.cartocdn.com/gl/voyager-gl-style/style.json';\n\n/\n Default picking radius in pixels\n * Creates a 5-pixel detection radius around the pointer for pickable objects\n * Makes thin lines and small shapes easier to hover\n */\nexport const PICKING_RADIUS = 5;\n\nexport const PARAMETERS = {\n depthWriteEnabled: true,\n depthCompare: 'always',\n depthBias: 0,\n blend: true,\n depthTest: false,\n blendColorSrcFactor: 'src-alpha',\n blendColorDstFactor: 'one-minus-src-alpha',\n blendAlphaSrcFactor: 'one',\n blendAlphaDstFactor: 'one-minus-src-alpha',\n blendColorOperation: 'add',\n blendAlphaOperation: 'add',\n};\n"],"mappings":"~~;;;;;;;;;;;;;;AAYA~~,MAAa,sBACX~~;AAEF~~,MAAa,uBACX;;;;;;AAOF,MAAa,iBAAiB~~;AAE9B~~,MAAa,aAAa;CACxB,mBAAmB;CACnB,cAAc;CACd,WAAW;CACX,OAAO;CACP,WAAW;CACX,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACtB"}
1	+ {"version":3,"file":"constants.js","names":[],"sources":["../../../src/deckgl/base-map/constants.ts"],"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/\n Dark theme base map style URL from Carto.\n * Provides a dark background for visualization layers.\n /\nexport const DARK_BASE_MAP_STYLE =\n 'https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json';\n\n/\n Light theme base map style URL from Carto.\n * Provides a light background for visualization layers.\n /\nexport const LIGHT_BASE_MAP_STYLE =\n 'https://tiles.basemaps.cartocdn.com/gl/voyager-gl-style/style.json';\n\n/\n Default picking radius in pixels\n * Creates a 5-pixel detection radius around the pointer for pickable objects\n * Makes thin lines and small shapes easier to hover\n /\nexport const PICKING_RADIUS = 5;\n\n/\n Default WebGL rendering parameters for Deck.gl.\n * Configures depth testing, blending, and rendering behavior for optimal layer compositing.\n */\nexport const PARAMETERS = {\n depthWriteEnabled: true,\n depthCompare: 'always',\n depthBias: 0,\n blend: true,\n depthTest: false,\n blendColorSrcFactor: 'src-alpha',\n blendColorDstFactor: 'one-minus-src-alpha',\n blendAlphaSrcFactor: 'one',\n blendAlphaDstFactor: 'one-minus-src-alpha',\n blendColorOperation: 'add',\n blendAlphaOperation: 'add',\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgBA,MAAa,sBACX;;;;;AAMF,MAAa,uBACX;;;;;;AAOF,MAAa,iBAAiB;;;;;AAM9B,MAAa,aAAa;CACxB,mBAAmB;CACnB,cAAc;CACd,WAAW;CACX,OAAO;CACP,WAAW;CACX,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACrB,qBAAqB;CACtB"}

package/dist/deckgl/base-map/controls.d.ts CHANGED Viewed

@@ -15,8 +15,13 @@ import { UniqueId } from "@accelint/core";
 import { MapRef } from "react-map-gl/maplibre";
 //#region src/deckgl/base-map/controls.d.ts
+/**
+ * Props for the MapControls component.
+ */
 type MapControlsProps = {
+  /** Unique identifier for the map instance */
   id: UniqueId;
+  /** Reference to the MapLibre map instance */
   mapRef: RefObject<MapRef | null>;
 };
 /**
@@ -24,6 +29,11 @@ type MapControlsProps = {
  *
  * This component is rendered inside BaseMap to wire up event listeners
  * for pan and zoom control events.
+ *
+ * @param props - Component props
+ * @param props.id - Unique identifier for the map instance
+ * @param props.mapRef - Reference to the MapLibre map instance
+ * @returns null (headless component)
  */
 declare function MapControls({
   id,

package/dist/deckgl/base-map/controls.js CHANGED Viewed

@@ -22,6 +22,11 @@ import { useOn } from "@accelint/bus/react";
 *
 * This component is rendered inside BaseMap to wire up event listeners
 * for pan and zoom control events.
+*
+* @param props - Component props
+* @param props.id - Unique identifier for the map instance
+* @param props.mapRef - Reference to the MapLibre map instance
+* @returns null (headless component)
 */
 function MapControls({ id, mapRef }) {
 	useOn(MapEvents.enablePan, (event) => {

package/dist/deckgl/base-map/controls.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"controls.js","names":[],"sources":["../../../src/deckgl/base-map/controls.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 { useOn } from '@accelint/bus/react';\nimport { MapEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { RefObject } from 'react';\nimport type { MapRef } from 'react-map-gl/maplibre';\nimport type {\n MapDisablePanEvent,\n MapDisableZoomEvent,\n MapEnablePanEvent,\n MapEnableZoomEvent,\n} from './types';\n\ntype MapControlsProps = {\n id: UniqueId;\n mapRef: RefObject<MapRef \| null>;\n};\n\n/\n Headless component that listens for map control events and applies them to the MapLibre instance.\n \n This component is rendered inside BaseMap to wire up event listeners\n * for pan and zoom control events.\n */\nexport function MapControls({ id, mapRef }: MapControlsProps) {\n useOn<MapEnablePanEvent>(MapEvents.enablePan, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().dragPan.enable();\n }\n });\n\n useOn<MapDisablePanEvent>(MapEvents.disablePan, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().dragPan.disable();\n }\n });\n\n useOn<MapEnableZoomEvent>(MapEvents.enableZoom, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().scrollZoom.enable();\n mapRef.current?.getMap().doubleClickZoom.enable();\n mapRef.current?.getMap().boxZoom.enable();\n }\n });\n\n useOn<MapDisableZoomEvent>(MapEvents.disableZoom, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().scrollZoom.disable();\n mapRef.current?.getMap().doubleClickZoom.disable();\n mapRef.current?.getMap().boxZoom.disable();\n }\n });\n\n return null;\n}\n"],"mappings":"~~;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA~~,SAAgB,YAAY,EAAE,IAAI,UAA4B;AAC5D,OAAyB,UAAU,YAAY,UAAU;AACvD,MAAI,MAAM,QAAQ,OAAO,GACvB,QAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;GAE3C;AAEF,OAA0B,UAAU,aAAa,UAAU;AACzD,MAAI,MAAM,QAAQ,OAAO,GACvB,QAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;GAE5C;AAEF,OAA0B,UAAU,aAAa,UAAU;AACzD,MAAI,MAAM,QAAQ,OAAO,IAAI;AAC3B,UAAO,SAAS,QAAQ,CAAC,WAAW,QAAQ;AAC5C,UAAO,SAAS,QAAQ,CAAC,gBAAgB,QAAQ;AACjD,UAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;;GAE3C;AAEF,OAA2B,UAAU,cAAc,UAAU;AAC3D,MAAI,MAAM,QAAQ,OAAO,IAAI;AAC3B,UAAO,SAAS,QAAQ,CAAC,WAAW,SAAS;AAC7C,UAAO,SAAS,QAAQ,CAAC,gBAAgB,SAAS;AAClD,UAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;;GAE5C;AAEF,QAAO"}
1	+ {"version":3,"file":"controls.js","names":[],"sources":["../../../src/deckgl/base-map/controls.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 { useOn } from '@accelint/bus/react';\nimport { MapEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { RefObject } from 'react';\nimport type { MapRef } from 'react-map-gl/maplibre';\nimport type {\n MapDisablePanEvent,\n MapDisableZoomEvent,\n MapEnablePanEvent,\n MapEnableZoomEvent,\n} from './types';\n\n/\n Props for the MapControls component.\n /\ntype MapControlsProps = {\n /* Unique identifier for the map instance /\n id: UniqueId;\n /* Reference to the MapLibre map instance /\n mapRef: RefObject<MapRef \| null>;\n};\n\n/\n Headless component that listens for map control events and applies them to the MapLibre instance.\n \n This component is rendered inside BaseMap to wire up event listeners\n * for pan and zoom control events.\n \n @param props - Component props\n * @param props.id - Unique identifier for the map instance\n * @param props.mapRef - Reference to the MapLibre map instance\n * @returns null (headless component)\n */\nexport function MapControls({ id, mapRef }: MapControlsProps) {\n useOn<MapEnablePanEvent>(MapEvents.enablePan, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().dragPan.enable();\n }\n });\n\n useOn<MapDisablePanEvent>(MapEvents.disablePan, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().dragPan.disable();\n }\n });\n\n useOn<MapEnableZoomEvent>(MapEvents.enableZoom, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().scrollZoom.enable();\n mapRef.current?.getMap().doubleClickZoom.enable();\n mapRef.current?.getMap().boxZoom.enable();\n }\n });\n\n useOn<MapDisableZoomEvent>(MapEvents.disableZoom, (event) => {\n if (event.payload.id === id) {\n mapRef.current?.getMap().scrollZoom.disable();\n mapRef.current?.getMap().doubleClickZoom.disable();\n mapRef.current?.getMap().boxZoom.disable();\n }\n });\n\n return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,YAAY,EAAE,IAAI,UAA4B;AAC5D,OAAyB,UAAU,YAAY,UAAU;AACvD,MAAI,MAAM,QAAQ,OAAO,GACvB,QAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;GAE3C;AAEF,OAA0B,UAAU,aAAa,UAAU;AACzD,MAAI,MAAM,QAAQ,OAAO,GACvB,QAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;GAE5C;AAEF,OAA0B,UAAU,aAAa,UAAU;AACzD,MAAI,MAAM,QAAQ,OAAO,IAAI;AAC3B,UAAO,SAAS,QAAQ,CAAC,WAAW,QAAQ;AAC5C,UAAO,SAAS,QAAQ,CAAC,gBAAgB,QAAQ;AACjD,UAAO,SAAS,QAAQ,CAAC,QAAQ,QAAQ;;GAE3C;AAEF,OAA2B,UAAU,cAAc,UAAU;AAC3D,MAAI,MAAM,QAAQ,OAAO,IAAI;AAC3B,UAAO,SAAS,QAAQ,CAAC,WAAW,SAAS;AAC7C,UAAO,SAAS,QAAQ,CAAC,gBAAgB,SAAS;AAClD,UAAO,SAAS,QAAQ,CAAC,QAAQ,SAAS;;GAE5C;AAEF,QAAO"}

package/dist/deckgl/base-map/events.d.ts CHANGED Viewed

@@ -1,5 +1,35 @@
 //#region src/deckgl/base-map/events.d.ts
+/**
+ * Namespace for all map-related events.
+ */
 declare const MapEventsNamespace = "map";
+/**
+ * Event keys for map interactions and control changes.
+ * These events are emitted through the event bus for communication between map components and consumers.
+ *
+ * @example
+ * ```typescript
+ * import { Broadcast } from '@accelint/bus';
+ * import { MapEvents } from '@accelint/map-toolkit/deckgl/base-map';
+ * import type { MapEventType } from '@accelint/map-toolkit/deckgl/base-map';
+ *
+ * const bus = Broadcast.getInstance<MapEventType>();
+ *
+ * // Listen for click events
+ * bus.on(MapEvents.click, (event) => {
+ *   console.log('Map clicked:', event.payload.info);
+ * });
+ *
+ * // Listen for viewport changes
+ * bus.on(MapEvents.viewport, (event) => {
+ *   console.log('Viewport changed:', event.payload.bounds);
+ * });
+ *
+ * // Emit control events
+ * bus.emit(MapEvents.disablePan, { id: mapId });
+ * bus.emit(MapEvents.enableZoom, { id: mapId });
+ * ```
+ */
 declare const MapEvents: {
   readonly click: "map:click";
   readonly hover: "map:hover";

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

@@ -12,7 +12,37 @@
 //#region src/deckgl/base-map/events.ts
+/**
+* Namespace for all map-related events.
+*/
 const MapEventsNamespace = "map";
+/**
+* Event keys for map interactions and control changes.
+* These events are emitted through the event bus for communication between map components and consumers.
+*
+* @example
+* ```typescript
+* import { Broadcast } from '@accelint/bus';
+* import { MapEvents } from '@accelint/map-toolkit/deckgl/base-map';
+* import type { MapEventType } from '@accelint/map-toolkit/deckgl/base-map';
+*
+* const bus = Broadcast.getInstance<MapEventType>();
+*
+* // Listen for click events
+* bus.on(MapEvents.click, (event) => {
+*   console.log('Map clicked:', event.payload.info);
+* });
+*
+* // Listen for viewport changes
+* bus.on(MapEvents.viewport, (event) => {
+*   console.log('Viewport changed:', event.payload.bounds);
+* });
+*
+* // Emit control events
+* bus.emit(MapEvents.disablePan, { id: mapId });
+* bus.emit(MapEvents.enableZoom, { id: mapId });
+* ```
+*/
 const MapEvents = {
 	click: `${MapEventsNamespace}:click`,
 	hover: `${MapEventsNamespace}:hover`,

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

	@@ -1 +1 @@
1	- {"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"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\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"}
1	+ {"version":3,"file":"events.js","names":[],"sources":["../../../src/deckgl/base-map/events.ts"],"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/\n Namespace for all map-related events.\n /\nexport const MapEventsNamespace = 'map';\n\n/\n Event keys for map interactions and control changes.\n * These events are emitted through the event bus for communication between map components and consumers.\n \n @example\n * ```typescript\n * import { Broadcast } from '@accelint/bus';\n * import { MapEvents } from '@accelint/map-toolkit/deckgl/base-map';\n * import type { MapEventType } from '@accelint/map-toolkit/deckgl/base-map';\n \n const bus = Broadcast.getInstance<MapEventType>();\n \n // Listen for click events\n * bus.on(MapEvents.click, (event) => {\n * console.log('Map clicked:', event.payload.info);\n * });\n \n // Listen for viewport changes\n * bus.on(MapEvents.viewport, (event) => {\n * console.log('Viewport changed:', event.payload.bounds);\n * });\n \n // Emit control events\n * bus.emit(MapEvents.disablePan, { id: mapId });\n * bus.emit(MapEvents.enableZoom, { id: mapId });\n * ```\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":";;;;;;;;;;;;;;;;;AAeA,MAAa,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BlC,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 CHANGED Viewed

@@ -11,7 +11,7 @@
  */
 import { BaseMapProps } from "./types.js";
-import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime3 from "react/jsx-runtime";
 //#region src/deckgl/base-map/index.d.ts
@@ -106,7 +106,7 @@ declare function BaseMap({
   onViewStateChange,
   pickingRadius,
   ...rest
-}: BaseMapProps): react_jsx_runtime1.JSX.Element;
+}: BaseMapProps): react_jsx_runtime3.JSX.Element;
 //#endregion
 export { BaseMap };
 //# sourceMappingURL=index.d.ts.map

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

@@ -30,6 +30,9 @@ import { Map, useControl } from "react-map-gl/maplibre";
 /**
 * Serializes PickingInfo for event bus transmission.
 * Omits viewport, layer, and sourceLayer (contain functions) but preserves layer IDs.
+*
+* @param info - The PickingInfo object from Deck.gl
+* @returns Serializable picking info with layer IDs extracted
 */
 function serializePickingInfo(info) {
 	const { viewport, layer, sourceLayer, ...infoRest } = info;
@@ -47,6 +50,12 @@ function serializeMjolnirEvent(event) {
 	}
 	return rest;
 }
+/**
+* Internal component that registers the Deck.gl instance as a MapLibre control.
+* Enables the Deck.gl canvas to render within the MapLibre GL map container.
+*
+* @returns null (headless component)
+*/
 function AddDeckglControl() {
 	const deckglInstance = useDeckgl();
 	useControl(() => deckglInstance);
@@ -163,6 +172,7 @@ function BaseMap({ id, className, children, controller = true, enableControlEven
 	const emitClick = useEmit(MapEvents.click);
 	const emitHover = useEmit(MapEvents.hover);
 	const emitViewport = useEmit(MapEvents.viewport);
+	const resizeTimeoutRef = useRef(null);
 	const handleClick = useCallback((info, event) => {
 		onClick?.(info, event);
 		emitClick({
@@ -194,6 +204,7 @@ function BaseMap({ id, className, children, controller = true, enableControlEven
 		onViewStateChange?.(params);
 		const { viewId, viewState: { latitude, longitude, zoom } } = params;
 		const viewport = deckglInstance._deck.getViewports()?.find((vp) => vp.id === viewId);
+		if (!viewport) return;
 		emitViewport({
 			id,
 			bounds: viewport?.getBounds(),
@@ -204,6 +215,24 @@ function BaseMap({ id, className, children, controller = true, enableControlEven
 			height: viewport?.height ?? 0
 		});
 	});
+	const handleResize = useEffectEvent((params) => {
+		if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current);
+		resizeTimeoutRef.current = setTimeout(() => {
+			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: params.width,
+					height: params.height
+				}
+			});
+		}, 200);
+	});
 	const handleLoad = useEffectEvent(() => {
 		const viewports = deckglInstance._deck.getViewports() ?? [];
 		for (const vp of viewports) handleViewStateChange({
@@ -242,6 +271,7 @@ function BaseMap({ id, className, children, controller = true, enableControlEven
 					pickingRadius: pickingRadius ?? PICKING_RADIUS,
 					onHover: handleHover,
 					onLoad: handleLoad,
+					onResize: handleResize,
 					onViewStateChange: handleViewStateChange,
 					parameters: {
 						...PARAMETERS,

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

	@@ -1 +1 @@
1	- {"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 { useMapCamera } from '../../camera';\nimport { getCursor } from '../../map-cursor/store';\nimport { DEFAULT_VIEW_STATE } from '../../shared/constants';\nimport { DARK_BASE_MAP_STYLE, PARAMETERS, PICKING_RADIUS } 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 } = useMapCamera(id, {\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 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(evt.viewState)}\n mapStyle={styleUrl}\n ref={mapRef}\n {...mapOptions}\n >\n <Deckgl\n {...rest}\n controller={controller}\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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"}
1	+ {"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 { useEffectEvent, useEmit } from '@accelint/bus/react';\nimport type { PickingInfo, ViewStateChangeParameters } from '@deck.gl/core';\nimport { Deckgl, useDeckgl } from '@deckgl-fiber-renderer/dom';\nimport 'client-only';\nimport type { IControl } from 'maplibre-gl';\nimport type { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';\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 { useMapCamera } from '../../camera';\nimport { getCursor } from '../../map-cursor/store';\nimport { DEFAULT_VIEW_STATE } from '../../shared/constants';\nimport { DARK_BASE_MAP_STYLE, PARAMETERS, PICKING_RADIUS } from './constants';\nimport { MapControls } from './controls';\nimport { MapEvents } from './events';\nimport { MapProvider } from './provider';\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 \n @param info - The PickingInfo object from Deck.gl\n * @returns Serializable picking info with layer IDs extracted\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 \n @param event - The MjolnirGestureEvent from Deck.gl\n * @returns Serializable gesture event with non-cloneable properties removed\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 \n @param event - The MjolnirPointerEvent from Deck.gl\n * @returns Serializable pointer event with non-cloneable properties removed\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 Internal component that registers the Deck.gl instance as a MapLibre control.\n * Enables the Deck.gl canvas to render within the MapLibre GL map container.\n \n @returns null (headless component)\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 } = useMapCamera(id, {\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 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 resizeTimeoutRef = useRef<NodeJS.Timeout \| null>(null);\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 if (!viewport) {\n return;\n }\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 handleResize = useEffectEvent((params) => {\n // Clear existing timeout\n if (resizeTimeoutRef.current) {\n clearTimeout(resizeTimeoutRef.current);\n }\n\n // Debounce\n resizeTimeoutRef.current = setTimeout(() => {\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: params.width,\n height: params.height,\n },\n } as ViewStateChangeParameters);\n }\n }, 200);\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(evt.viewState)}\n mapStyle={styleUrl}\n ref={mapRef}\n {...mapOptions}\n >\n <Deckgl\n {...rest}\n controller={controller}\n interleaved={interleaved}\n getCursor={handleGetCursor}\n useDevicePixels={useDevicePixels}\n onClick={handleClick}\n pickingRadius={pickingRadius ?? PICKING_RADIUS}\n onHover={handleHover}\n onLoad={handleLoad}\n onResize={handleResize}\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/saved-viewports/index.d.ts CHANGED Viewed

@@ -15,17 +15,92 @@ import { MapViewState } from "@deck.gl/core";
 import { RequireAllOrNone } from "type-fest";
 //#region src/deckgl/saved-viewports/index.d.ts
+/**
+ * Base options required for saved viewport functionality.
+ */
 type BaseOptions = {
+  /** Optional identifier to namespace saved viewports for multiple map instances */
   uniqueIdentifier?: string;
+  /** Milliseconds to hold a key before saving (default: 1000) */
   threshold?: number;
+  /** Function that returns the current map viewport state */
   getCurrentViewport: () => MapViewState;
+  /** Function that receives a viewport state and applies it to the map */
   setCurrentViewport: (viewport: MapViewState) => void;
 };
+/**
+ * Optional custom storage functions for persisting viewports.
+ * Both functions must be provided together or omitted entirely.
+ */
 type PersistOptions = RequireAllOrNone<{
+  /** Custom function to retrieve saved viewports from storage */
   getSavedViewport: (id: KeyCombinationId, uniqueIdentifier?: string) => MapViewState;
+  /** Custom function to persist saved viewports to storage */
   setSavedViewport: (id: KeyCombinationId, viewport: MapViewState, uniqueIdentifier?: string) => void;
 }>;
+/**
+ * Configuration options for creating a saved viewport hotkey system.
+ * Combines hotkey options with viewport management callbacks and optional custom storage.
+ */
 type SavedViewportOptions = Partial<HotkeyOptions> & BaseOptions & PersistOptions;
+/**
+ * Creates a React hook that registers hotkeys for saving and restoring map viewports.
+ *
+ * By default, uses number keys 0-9 where:
+ * - **Hold** a key for the threshold duration (default 1s) to save the current viewport
+ * - **Tap** a key to restore the saved viewport
+ *
+ * Viewports are persisted to localStorage by default but can be customized with
+ * `getSavedViewport` and `setSavedViewport` options.
+ *
+ * @param options - Configuration for viewport saving behavior and storage
+ * @returns A React hook function that must be called within a component to activate hotkeys
+ *
+ * @example
+ * ```tsx
+ * import { Broadcast } from '@accelint/bus';
+ * import { useOn } from '@accelint/bus/react';
+ * import { uuid } from '@accelint/core';
+ * import { BaseMap } from '@accelint/map-toolkit/deckgl';
+ * import { MapEvents } from '@accelint/map-toolkit/deckgl/base-map';
+ * import { CameraEventTypes } from '@accelint/map-toolkit/camera';
+ * import { createSavedViewport } from '@accelint/map-toolkit/deckgl/saved-viewports';
+ * import { globalBind } from '@accelint/hotkey-manager';
+ * import type { MapViewState } from '@deck.gl/core';
+ * import type { CameraEvent } from '@accelint/map-toolkit/camera';
+ * import type { MapViewportEvent, MapViewportPayload } from '@accelint/map-toolkit/deckgl/base-map';
+ *
+ * globalBind();
+ *
+ * const MAP_ID = uuid();
+ * const cameraBus = Broadcast.getInstance<CameraEvent>();
+ * let currentViewport: MapViewportPayload;
+ *
+ * const useSavedViewportHotkey = createSavedViewport({
+ *   threshold: 1000,
+ *   getCurrentViewport: () => currentViewport,
+ *   setCurrentViewport: (newState: MapViewState) => {
+ *     currentViewport = { ...currentViewport, ...newState };
+ *     cameraBus.emit(CameraEventTypes.setCenter, {
+ *       id: MAP_ID,
+ *       latitude: newState.latitude ?? currentViewport.latitude,
+ *       longitude: newState.longitude ?? currentViewport.longitude,
+ *       zoom: newState.zoom,
+ *     });
+ *   },
+ * });
+ *
+ * export function MapView() {
+ *   useSavedViewportHotkey();
+ *
+ *   useOn<MapViewportEvent>(MapEvents.viewport, (event) => {
+ *     currentViewport = { ...currentViewport, ...event.payload };
+ *   });
+ *
+ *   return <BaseMap id={MAP_ID} className="w-full h-full" />;
+ * }
+ * ```
+ */
 declare const createSavedViewport: (options: SavedViewportOptions) => ReturnType<typeof registerHotkey>;
 //#endregion
 export { SavedViewportOptions, createSavedViewport };