@accelint/map-toolkit 1.2.0 → 1.3.0

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

@@ -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 };

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

@@ -15,6 +15,64 @@ import { STORAGE_ID, persist, retrieve } from "./storage.js";
 import { Keycode, registerHotkey } from "@accelint/hotkey-manager";
 
 //#region src/deckgl/saved-viewports/index.ts
+/**
+* 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" />;
+* }
+* ```
+*/
 const createSavedViewport = (options) => {
 	const setFn = options.setSavedViewport ?? persist;
 	const getFn = options.getSavedViewport ?? retrieve;

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

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

@@ -13,8 +13,59 @@
 import { MapViewState } from "@deck.gl/core";
 
 //#region src/deckgl/saved-viewports/storage.d.ts
+/**
+ * Base storage key for saved viewports in localStorage.
+ */
 declare const STORAGE_ID = "deckgl-saved-viewports";
+/**
+ * Persists a viewport state to localStorage.
+ *
+ * Saves the viewport under the given ID within a namespaced container.
+ * If the container doesn't exist, creates it. If the ID already exists, overwrites it.
+ *
+ * @param id - Unique identifier for this viewport (typically a key combination ID)
+ * @param obj - The MapViewState to persist
+ * @param uniqueIdentifier - Optional namespace for multiple map instances
+ *
+ * @example
+ * ```typescript
+ * import { persist } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';
+ *
+ * const viewport = {
+ *   latitude: 38.9072,
+ *   longitude: -77.0369,
+ *   zoom: 10,
+ *   pitch: 0,
+ *   bearing: 0,
+ * };
+ *
+ * persist('Digit1', viewport);
+ * persist('Digit2', viewport, 'main-map');
+ * ```
+ */
 declare const persist: (id: string, obj: MapViewState, uniqueIdentifier?: string) => void;
+/**
+ * Retrieves a saved viewport state from localStorage.
+ *
+ * Returns the viewport associated with the given ID, or undefined if not found.
+ * Logs a warning if the viewport doesn't exist.
+ *
+ * @param id - Unique identifier for the viewport to retrieve
+ * @param uniqueIdentifier - Optional namespace for multiple map instances
+ * @returns The saved MapViewState or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * import { retrieve } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';
+ *
+ * const viewport = retrieve('Digit1');
+ * if (viewport) {
+ *   console.log('Restored viewport:', viewport);
+ * }
+ *
+ * const mainMapViewport = retrieve('Digit1', 'main-map');
+ * ```
+ */
 declare const retrieve: (id: string, uniqueIdentifier?: string) => any;
 //#endregion
 export { STORAGE_ID, persist, retrieve };

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

@@ -20,8 +20,24 @@ const logger = getLogger({
 	prefix: "[SavedViewports]",
 	pretty: true
 });
+/**
+* Base storage key for saved viewports in localStorage.
+*/
 const STORAGE_ID = "deckgl-saved-viewports";
+/**
+* Generates a storage key, optionally namespaced by unique identifier.
+*
+* @param uniqueIdentifier - Optional namespace for multiple map instances
+* @returns Storage key string
+*/
 const getContainerKey = (uniqueIdentifier) => uniqueIdentifier ? `${STORAGE_ID}-${uniqueIdentifier}` : STORAGE_ID;
+/**
+* Retrieves the storage container from localStorage.
+* Returns empty object if parsing fails or key doesn't exist.
+*
+* @param containerKey - The storage key to retrieve
+* @returns Parsed storage container object
+*/
 const getContainer = (containerKey) => {
 	try {
 		return JSON.parse(localStorage.getItem(containerKey) ?? "{}");
@@ -30,12 +46,60 @@ const getContainer = (containerKey) => {
 		return {};
 	}
 };
+/**
+* Persists a viewport state to localStorage.
+*
+* Saves the viewport under the given ID within a namespaced container.
+* If the container doesn't exist, creates it. If the ID already exists, overwrites it.
+*
+* @param id - Unique identifier for this viewport (typically a key combination ID)
+* @param obj - The MapViewState to persist
+* @param uniqueIdentifier - Optional namespace for multiple map instances
+*
+* @example
+* ```typescript
+* import { persist } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';
+*
+* const viewport = {
+*   latitude: 38.9072,
+*   longitude: -77.0369,
+*   zoom: 10,
+*   pitch: 0,
+*   bearing: 0,
+* };
+*
+* persist('Digit1', viewport);
+* persist('Digit2', viewport, 'main-map');
+* ```
+*/
 const persist = (id, obj, uniqueIdentifier) => {
 	const containerKey = getContainerKey(uniqueIdentifier);
 	const container = getContainer(containerKey);
 	container[id] = obj;
 	localStorage.setItem(containerKey, JSON.stringify(container));
 };
+/**
+* Retrieves a saved viewport state from localStorage.
+*
+* Returns the viewport associated with the given ID, or undefined if not found.
+* Logs a warning if the viewport doesn't exist.
+*
+* @param id - Unique identifier for the viewport to retrieve
+* @param uniqueIdentifier - Optional namespace for multiple map instances
+* @returns The saved MapViewState or undefined if not found
+*
+* @example
+* ```typescript
+* import { retrieve } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';
+*
+* const viewport = retrieve('Digit1');
+* if (viewport) {
+*   console.log('Restored viewport:', viewport);
+* }
+*
+* const mainMapViewport = retrieve('Digit1', 'main-map');
+* ```
+*/
 const retrieve = (id, uniqueIdentifier) => {
 	const obj = getContainer(getContainerKey(uniqueIdentifier))[id];
 	if (!obj) logger.warn(`Object with id: ${id} does not exist`);

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

@@ -1 +1 @@
-{"version":3,"file":"storage.js","names":[],"sources":["../../../src/deckgl/saved-viewports/storage.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\nimport { getLogger } from '@accelint/logger';\nimport type { MapViewState } from '@deck.gl/core';\n\nconst logger = getLogger({\n  enabled:\n    process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n  level: 'warn',\n  prefix: '[SavedViewports]',\n  pretty: true,\n});\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    logger.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    logger.warn(`Object with id: ${id} does not exist`);\n  }\n  return obj;\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;AAEF,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,SAAO,KACL,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,QAAO,KAAK,mBAAmB,GAAG,iBAAiB;AAErD,QAAO"}
+{"version":3,"file":"storage.js","names":[],"sources":["../../../src/deckgl/saved-viewports/storage.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\nimport { getLogger } from '@accelint/logger';\nimport type { MapViewState } from '@deck.gl/core';\n\nconst logger = getLogger({\n  enabled:\n    process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n  level: 'warn',\n  prefix: '[SavedViewports]',\n  pretty: true,\n});\n\n/**\n * Base storage key for saved viewports in localStorage.\n */\nexport const STORAGE_ID = 'deckgl-saved-viewports';\n\n/**\n * Generates a storage key, optionally namespaced by unique identifier.\n *\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n * @returns Storage key string\n */\nconst getContainerKey = (uniqueIdentifier?: string) =>\n  uniqueIdentifier ? `${STORAGE_ID}-${uniqueIdentifier}` : STORAGE_ID;\n\n/**\n * Retrieves the storage container from localStorage.\n * Returns empty object if parsing fails or key doesn't exist.\n *\n * @param containerKey - The storage key to retrieve\n * @returns Parsed storage container object\n */\nconst getContainer = (containerKey: string) => {\n  try {\n    return JSON.parse(localStorage.getItem(containerKey) ?? '{}');\n  } catch {\n    logger.warn(\n      `Failed to parse storage container for key: ${containerKey}, returning empty container.`,\n    );\n    return {};\n  }\n};\n\n/**\n * Persists a viewport state to localStorage.\n *\n * Saves the viewport under the given ID within a namespaced container.\n * If the container doesn't exist, creates it. If the ID already exists, overwrites it.\n *\n * @param id - Unique identifier for this viewport (typically a key combination ID)\n * @param obj - The MapViewState to persist\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n *\n * @example\n * ```typescript\n * import { persist } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';\n *\n * const viewport = {\n *   latitude: 38.9072,\n *   longitude: -77.0369,\n *   zoom: 10,\n *   pitch: 0,\n *   bearing: 0,\n * };\n *\n * persist('Digit1', viewport);\n * persist('Digit2', viewport, 'main-map');\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\n/**\n * Retrieves a saved viewport state from localStorage.\n *\n * Returns the viewport associated with the given ID, or undefined if not found.\n * Logs a warning if the viewport doesn't exist.\n *\n * @param id - Unique identifier for the viewport to retrieve\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n * @returns The saved MapViewState or undefined if not found\n *\n * @example\n * ```typescript\n * import { retrieve } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';\n *\n * const viewport = retrieve('Digit1');\n * if (viewport) {\n *   console.log('Restored viewport:', viewport);\n * }\n *\n * const mainMapViewport = retrieve('Digit1', 'main-map');\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    logger.warn(`Object with id: ${id} does not exist`);\n  }\n  return obj;\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;;;;AAKF,MAAa,aAAa;;;;;;;AAQ1B,MAAM,mBAAmB,qBACvB,mBAAmB,GAAG,WAAW,GAAG,qBAAqB;;;;;;;;AAS3D,MAAM,gBAAgB,iBAAyB;AAC7C,KAAI;AACF,SAAO,KAAK,MAAM,aAAa,QAAQ,aAAa,IAAI,KAAK;SACvD;AACN,SAAO,KACL,8CAA8C,aAAa,8BAC5D;AACD,SAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8Bb,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;;;;;;;;;;;;;;;;;;;;;;;;AAyB/D,MAAa,YAAY,IAAY,qBAA8B;CAGjE,MAAM,MADY,aADG,gBAAgB,iBAAiB,CACV,CACtB;AACtB,KAAI,CAAC,IACH,QAAO,KAAK,mBAAmB,GAAG,iBAAiB;AAErD,QAAO"}

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

@@ -17,8 +17,10 @@ import { DEFAULT_COLORS } from "../shared/constants.js";
 
 //#region src/deckgl/shapes/display-shape-layer/constants.ts
 /**
-* Map interaction constants
-* Values derived from ngc2 for consistency
+* Map interaction constants.
+*
+* Values derived from ngc2 for consistency with existing UI patterns.
+* Controls sizing and interaction feedback for shape rendering.
 */
 const MAP_INTERACTION = {
 	LINE_WIDTH_MIN_PIXELS: 1,
@@ -26,15 +28,21 @@ const MAP_INTERACTION = {
 	ICON_HOVER_SIZE_INCREASE: 5
 };
 /**
-* Selection highlight configuration
+* Selection highlight configuration.
+*
+* Controls the appearance of selected shapes, including highlight color
+* and icon size adjustments for Point shapes.
 */
 const SELECTION_HIGHLIGHT = {
 	COLOR: DEFAULT_COLORS.highlight,
 	ICON_SIZE_INCREASE: 8
 };
 /**
-* Coffin corners configuration for Point selection/hover feedback
-* Coffin corners are bracket-like corners that appear around points
+* Coffin corners configuration for Point selection/hover feedback.
+*
+* Coffin corners are bracket-like corners that appear around Point shapes
+* with icons to indicate hover and selection states. They provide visual
+* feedback without obscuring the icon itself.
 */
 const COFFIN_CORNERS = {
 	HOVER_ICON: "coffin-corners-hover",
@@ -43,7 +51,11 @@ const COFFIN_CORNERS = {
 	SIZE: 38
 };
 /**
-* Default props for DisplayShapeLayer
+* Default props for DisplayShapeLayer.
+*
+* Provides sensible defaults for interactive shape display with labels,
+* standard opacity handling, and minimal visual feedback. These can be
+* overridden via layer props.
 */
 const DEFAULT_DISPLAY_PROPS = {
 	pickable: true,

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

@@ -1 +1 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/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'use client';\n\nimport { DEFAULT_COLORS } from '../shared/constants';\n\n/**\n * Map interaction constants\n * Values derived from ngc2 for consistency\n */\nexport const MAP_INTERACTION = {\n  LINE_WIDTH_MIN_PIXELS: 1, // Minimum line width in pixels\n  ICON_SIZE: 38, // Size of shape icons\n  ICON_HOVER_SIZE_INCREASE: 5, // Additional pixels added on hover\n} as const;\n\n/**\n * Selection highlight configuration\n */\nexport const SELECTION_HIGHLIGHT = {\n  /** Uses DEFAULT_COLORS.highlight from shared constants */\n  COLOR: DEFAULT_COLORS.highlight,\n  ICON_SIZE_INCREASE: 8, // Additional pixels for highlight icon\n} as const;\n\n/**\n * Coffin corners configuration for Point selection/hover feedback\n * Coffin corners are bracket-like corners that appear around points\n */\nexport const COFFIN_CORNERS = {\n  /** Icon name for hover state (white corners with background fill) */\n  HOVER_ICON: 'coffin-corners-hover',\n  /** Icon name for selected state (blue corners, no fill) */\n  SELECTED_ICON: 'coffin-corners-selected',\n  /** Icon name for selected+hover state (blue corners with background fill) */\n  SELECTED_HOVER_ICON: 'coffin-corners-selected-hover',\n  /** Size of the coffin corners icon */\n  SIZE: 38,\n} as const;\n\n/**\n * Default props for DisplayShapeLayer\n */\nexport const DEFAULT_DISPLAY_PROPS = {\n  pickable: true,\n  showLabels: 'always' as const,\n  showHighlight: false,\n  applyBaseOpacity: true,\n  highlightColor: SELECTION_HIGHLIGHT.COLOR,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,kBAAkB;CAC7B,uBAAuB;CACvB,WAAW;CACX,0BAA0B;CAC3B;;;;AAKD,MAAa,sBAAsB;CAEjC,OAAO,eAAe;CACtB,oBAAoB;CACrB;;;;;AAMD,MAAa,iBAAiB;CAE5B,YAAY;CAEZ,eAAe;CAEf,qBAAqB;CAErB,MAAM;CACP;;;;AAKD,MAAa,wBAAwB;CACnC,UAAU;CACV,YAAY;CACZ,eAAe;CACf,kBAAkB;CAClB,gBAAgB,oBAAoB;CACrC"}
+{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/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'use client';\n\nimport { DEFAULT_COLORS } from '../shared/constants';\n\n/**\n * Map interaction constants.\n *\n * Values derived from ngc2 for consistency with existing UI patterns.\n * Controls sizing and interaction feedback for shape rendering.\n */\nexport const MAP_INTERACTION = {\n  LINE_WIDTH_MIN_PIXELS: 1, // Minimum line width in pixels\n  ICON_SIZE: 38, // Size of shape icons\n  ICON_HOVER_SIZE_INCREASE: 5, // Additional pixels added on hover\n} as const;\n\n/**\n * Selection highlight configuration.\n *\n * Controls the appearance of selected shapes, including highlight color\n * and icon size adjustments for Point shapes.\n */\nexport const SELECTION_HIGHLIGHT = {\n  /** Uses DEFAULT_COLORS.highlight from shared constants */\n  COLOR: DEFAULT_COLORS.highlight,\n  ICON_SIZE_INCREASE: 8, // Additional pixels for highlight icon\n} as const;\n\n/**\n * Coffin corners configuration for Point selection/hover feedback.\n *\n * Coffin corners are bracket-like corners that appear around Point shapes\n * with icons to indicate hover and selection states. They provide visual\n * feedback without obscuring the icon itself.\n */\nexport const COFFIN_CORNERS = {\n  /** Icon name for hover state (white corners with background fill) */\n  HOVER_ICON: 'coffin-corners-hover',\n  /** Icon name for selected state (blue corners, no fill) */\n  SELECTED_ICON: 'coffin-corners-selected',\n  /** Icon name for selected+hover state (blue corners with background fill) */\n  SELECTED_HOVER_ICON: 'coffin-corners-selected-hover',\n  /** Size of the coffin corners icon */\n  SIZE: 38,\n} as const;\n\n/**\n * Default props for DisplayShapeLayer.\n *\n * Provides sensible defaults for interactive shape display with labels,\n * standard opacity handling, and minimal visual feedback. These can be\n * overridden via layer props.\n */\nexport const DEFAULT_DISPLAY_PROPS = {\n  pickable: true,\n  showLabels: 'always' as const,\n  showHighlight: false,\n  applyBaseOpacity: true,\n  highlightColor: SELECTION_HIGHLIGHT.COLOR,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,kBAAkB;CAC7B,uBAAuB;CACvB,WAAW;CACX,0BAA0B;CAC3B;;;;;;;AAQD,MAAa,sBAAsB;CAEjC,OAAO,eAAe;CACtB,oBAAoB;CACrB;;;;;;;;AASD,MAAa,iBAAiB;CAE5B,YAAY;CAEZ,eAAe;CAEf,qBAAqB;CAErB,MAAM;CACP;;;;;;;;AASD,MAAa,wBAAwB;CACnC,UAAU;CACV,YAAY;CACZ,eAAe;CACf,kBAAkB;CAClB,gBAAgB,oBAAoB;CACrC"}

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

@@ -17,6 +17,13 @@ declare global {
   namespace React {
     namespace JSX {
       interface IntrinsicElements {
+        /**
+         * A read-only Deck.gl Fiber layer for displaying geographic shapes with interactive features.
+         *
+         * Supports Point, LineString, Polygon, and Circle geometries with customizable styling,
+         * icons, labels, selection, and hover effects. Ideal for rendering shapes from external
+         * APIs or displaying geographic data without editing capabilities.
+         */
         displayShapeLayer: DisplayShapeLayerProps;
       }
     }

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

@@ -1 +1 @@
-{"version":3,"file":"fiber.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/fiber.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\nimport { extend } from '@deckgl-fiber-renderer/dom';\nimport { DisplayShapeLayer } from './index';\nimport type { DisplayShapeLayerProps } from './types';\n\nextend({ DisplayShapeLayer });\n\ndeclare global {\n  namespace React {\n    // biome-ignore lint/style/useNamingConvention: Built-in React namespace.\n    namespace JSX {\n      interface IntrinsicElements {\n        displayShapeLayer: DisplayShapeLayerProps;\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,OAAO,EAAE,mBAAmB,CAAC"}
+{"version":3,"file":"fiber.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/fiber.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\nimport { extend } from '@deckgl-fiber-renderer/dom';\nimport { DisplayShapeLayer } from './index';\nimport type { DisplayShapeLayerProps } from './types';\n\nextend({ DisplayShapeLayer });\n\ndeclare global {\n  namespace React {\n    // biome-ignore lint/style/useNamingConvention: Built-in React namespace.\n    namespace JSX {\n      interface IntrinsicElements {\n        /**\n         * A read-only Deck.gl Fiber layer for displaying geographic shapes with interactive features.\n         *\n         * Supports Point, LineString, Polygon, and Circle geometries with customizable styling,\n         * icons, labels, selection, and hover effects. Ideal for rendering shapes from external\n         * APIs or displaying geographic data without editing capabilities.\n         */\n        displayShapeLayer: DisplayShapeLayerProps;\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,OAAO,EAAE,mBAAmB,CAAC"}

package/dist/deckgl/shapes/display-shape-layer/utils/display-style.js

@@ -18,15 +18,53 @@ import { getLineWidth, normalizeColor } from "../../shared/utils/style-utils.js"
 
 //#region src/deckgl/shapes/display-shape-layer/utils/display-style.ts
 /**
-* Get hover-enhanced border/outline width
+* Get hover-enhanced border/outline width.
+*
+* Calculates the line width for a feature, increasing it when hovered to provide
+* visual feedback. The hover effect adds a fixed pixel increase to the base width.
+*
+* @param feature - The styled feature to calculate width for
+* @param isHovered - Whether the feature is currently being hovered
+* @returns The calculated line width in pixels
+*
+* @example
+* ```typescript
+* import { getHoverLineWidth } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/display-style';
+* import type { StyledFeature } from '@accelint/map-toolkit/deckgl/shapes/shared/types';
+*
+* const feature: StyledFeature = {
+*   properties: { styleProperties: { lineWidth: 2 } }
+* };
+*
+* const width = getHoverLineWidth(feature, true);
+* // Returns: 2 + HOVER_WIDTH_INCREASE (typically 4 pixels total)
+* ```
 */
 function getHoverLineWidth(feature, isHovered) {
 	const baseWidth = getLineWidth(feature);
 	return isHovered ? baseWidth + HOVER_WIDTH_INCREASE : baseWidth;
 }
 /**
-* Get selection highlight color
-* Returns the default highlight color or allows custom opacity override
+* Get selection highlight color.
+*
+* Returns the default highlight color with optional custom opacity override.
+* The highlight color is used to indicate selected features on the map.
+*
+* @param opacity - Optional opacity value (0-1 range), overrides default opacity
+* @returns RGBA color array [red, green, blue, alpha] with values 0-255
+*
+* @example
+* ```typescript
+* import { getHighlightColor } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/display-style';
+*
+* // Use default highlight color with default opacity
+* const defaultColor = getHighlightColor();
+* // Returns: [r, g, b, a] from DEFAULT_COLORS.highlight
+*
+* // Use custom opacity (50% transparent)
+* const semiTransparent = getHighlightColor(0.5);
+* // Returns: [r, g, b, 127]
+* ```
 */
 function getHighlightColor(opacity) {
 	const rgba = normalizeColor(DEFAULT_COLORS.highlight);
@@ -39,7 +77,26 @@ function getHighlightColor(opacity) {
 	return rgba;
 }
 /**
-* Get highlight border/outline width (base width + increase)
+* Get highlight border/outline width.
+*
+* Calculates the line width for a selected/highlighted feature by adding a fixed
+* pixel increase to the base width. This makes selected features more prominent.
+*
+* @param feature - The styled feature to calculate width for
+* @returns The calculated line width in pixels (base width + HIGHLIGHT_WIDTH_INCREASE)
+*
+* @example
+* ```typescript
+* import { getHighlightLineWidth } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/display-style';
+* import type { StyledFeature } from '@accelint/map-toolkit/deckgl/shapes/shared/types';
+*
+* const feature: StyledFeature = {
+*   properties: { styleProperties: { lineWidth: 2 } }
+* };
+*
+* const width = getHighlightLineWidth(feature);
+* // Returns: 2 + HIGHLIGHT_WIDTH_INCREASE (typically 5 pixels total)
+* ```
 */
 function getHighlightLineWidth(feature) {
 	return getLineWidth(feature) + HIGHLIGHT_WIDTH_INCREASE;

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

@@ -1 +1 @@
-{"version":3,"file":"display-style.js","names":[],"sources":["../../../../../src/deckgl/shapes/display-shape-layer/utils/display-style.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'use client';\n\nimport {\n  DEFAULT_COLORS,\n  HIGHLIGHT_WIDTH_INCREASE,\n  HOVER_WIDTH_INCREASE,\n} from '../../shared/constants';\nimport { getLineWidth, normalizeColor } from '../../shared/utils/style-utils';\nimport type { StyledFeature } from '../../shared/types';\n\n/**\n * Get hover-enhanced border/outline width\n */\nexport function getHoverLineWidth(\n  feature: StyledFeature,\n  isHovered: boolean,\n): number {\n  const baseWidth = getLineWidth(feature);\n  return isHovered ? baseWidth + HOVER_WIDTH_INCREASE : baseWidth;\n}\n\n/**\n * Get selection highlight color\n * Returns the default highlight color or allows custom opacity override\n */\nexport function getHighlightColor(\n  opacity?: number,\n): [number, number, number, number] {\n  const rgba = normalizeColor(DEFAULT_COLORS.highlight);\n\n  if (opacity !== undefined) {\n    return [rgba[0], rgba[1], rgba[2], Math.round(opacity * 255)];\n  }\n\n  return rgba;\n}\n\n/**\n * Get highlight border/outline width (base width + increase)\n */\nexport function getHighlightLineWidth(feature: StyledFeature): number {\n  const baseWidth = getLineWidth(feature);\n  return baseWidth + HIGHLIGHT_WIDTH_INCREASE;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,kBACd,SACA,WACQ;CACR,MAAM,YAAY,aAAa,QAAQ;AACvC,QAAO,YAAY,YAAY,uBAAuB;;;;;;AAOxD,SAAgB,kBACd,SACkC;CAClC,MAAM,OAAO,eAAe,eAAe,UAAU;AAErD,KAAI,YAAY,OACd,QAAO;EAAC,KAAK;EAAI,KAAK;EAAI,KAAK;EAAI,KAAK,MAAM,UAAU,IAAI;EAAC;AAG/D,QAAO;;;;;AAMT,SAAgB,sBAAsB,SAAgC;AAEpE,QADkB,aAAa,QAAQ,GACpB"}
+{"version":3,"file":"display-style.js","names":[],"sources":["../../../../../src/deckgl/shapes/display-shape-layer/utils/display-style.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'use client';\n\nimport {\n  DEFAULT_COLORS,\n  HIGHLIGHT_WIDTH_INCREASE,\n  HOVER_WIDTH_INCREASE,\n} from '../../shared/constants';\nimport { getLineWidth, normalizeColor } from '../../shared/utils/style-utils';\nimport type { StyledFeature } from '../../shared/types';\n\n/**\n * Get hover-enhanced border/outline width.\n *\n * Calculates the line width for a feature, increasing it when hovered to provide\n * visual feedback. The hover effect adds a fixed pixel increase to the base width.\n *\n * @param feature - The styled feature to calculate width for\n * @param isHovered - Whether the feature is currently being hovered\n * @returns The calculated line width in pixels\n *\n * @example\n * ```typescript\n * import { getHoverLineWidth } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/display-style';\n * import type { StyledFeature } from '@accelint/map-toolkit/deckgl/shapes/shared/types';\n *\n * const feature: StyledFeature = {\n *   properties: { styleProperties: { lineWidth: 2 } }\n * };\n *\n * const width = getHoverLineWidth(feature, true);\n * // Returns: 2 + HOVER_WIDTH_INCREASE (typically 4 pixels total)\n * ```\n */\nexport function getHoverLineWidth(\n  feature: StyledFeature,\n  isHovered: boolean,\n): number {\n  const baseWidth = getLineWidth(feature);\n  return isHovered ? baseWidth + HOVER_WIDTH_INCREASE : baseWidth;\n}\n\n/**\n * Get selection highlight color.\n *\n * Returns the default highlight color with optional custom opacity override.\n * The highlight color is used to indicate selected features on the map.\n *\n * @param opacity - Optional opacity value (0-1 range), overrides default opacity\n * @returns RGBA color array [red, green, blue, alpha] with values 0-255\n *\n * @example\n * ```typescript\n * import { getHighlightColor } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/display-style';\n *\n * // Use default highlight color with default opacity\n * const defaultColor = getHighlightColor();\n * // Returns: [r, g, b, a] from DEFAULT_COLORS.highlight\n *\n * // Use custom opacity (50% transparent)\n * const semiTransparent = getHighlightColor(0.5);\n * // Returns: [r, g, b, 127]\n * ```\n */\nexport function getHighlightColor(\n  opacity?: number,\n): [number, number, number, number] {\n  const rgba = normalizeColor(DEFAULT_COLORS.highlight);\n\n  if (opacity !== undefined) {\n    return [rgba[0], rgba[1], rgba[2], Math.round(opacity * 255)];\n  }\n\n  return rgba;\n}\n\n/**\n * Get highlight border/outline width.\n *\n * Calculates the line width for a selected/highlighted feature by adding a fixed\n * pixel increase to the base width. This makes selected features more prominent.\n *\n * @param feature - The styled feature to calculate width for\n * @returns The calculated line width in pixels (base width + HIGHLIGHT_WIDTH_INCREASE)\n *\n * @example\n * ```typescript\n * import { getHighlightLineWidth } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/display-style';\n * import type { StyledFeature } from '@accelint/map-toolkit/deckgl/shapes/shared/types';\n *\n * const feature: StyledFeature = {\n *   properties: { styleProperties: { lineWidth: 2 } }\n * };\n *\n * const width = getHighlightLineWidth(feature);\n * // Returns: 2 + HIGHLIGHT_WIDTH_INCREASE (typically 5 pixels total)\n * ```\n */\nexport function getHighlightLineWidth(feature: StyledFeature): number {\n  const baseWidth = getLineWidth(feature);\n  return baseWidth + HIGHLIGHT_WIDTH_INCREASE;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,kBACd,SACA,WACQ;CACR,MAAM,YAAY,aAAa,QAAQ;AACvC,QAAO,YAAY,YAAY,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;AAyBxD,SAAgB,kBACd,SACkC;CAClC,MAAM,OAAO,eAAe,eAAe,UAAU;AAErD,KAAI,YAAY,OACd,QAAO;EAAC,KAAK;EAAI,KAAK;EAAI,KAAK;EAAI,KAAK,MAAM,UAAU,IAAI;EAAC;AAG/D,QAAO;;;;;;;;;;;;;;;;;;;;;;;;AAyBT,SAAgB,sBAAsB,SAAgC;AAEpE,QADkB,aAAa,QAAQ,GACpB"}

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

@@ -14,7 +14,10 @@ import "../../shared/types.js";
 
 //#region src/deckgl/shapes/display-shape-layer/utils/labels.d.ts
 /**
- * Label positioning information including coordinates and screen-space offsets
+ * Label positioning information including coordinates and screen-space offsets.
+ *
+ * Defines where a label should be positioned on the map, combining geographic coordinates
+ * with text alignment and pixel-level offsets for precise placement.
  */
 interface LabelPosition2d {
   /** Geographic coordinates [longitude, latitude] */
@@ -27,19 +30,30 @@ interface LabelPosition2d {
   pixelOffset: [number, number];
 }
 /**
- * Vertical label position relative to anchor point
+ * Vertical label position relative to anchor point.
+ *
+ * Controls how the label aligns vertically with its anchor coordinate:
+ * - `'top'`: Label text appears below the anchor point
+ * - `'middle'`: Label text is vertically centered on the anchor point
+ * - `'bottom'`: Label text appears above the anchor point
  */
 type LabelVerticalPosition = 'top' | 'middle' | 'bottom';
 /**
- * Horizontal label position relative to anchor point
+ * Horizontal label position relative to anchor point.
+ *
+ * Controls how the label aligns horizontally with its anchor coordinate:
+ * - `'left'`: Label text appears to the right of the anchor point
+ * - `'center'`: Label text is horizontally centered on the anchor point
+ * - `'right'`: Label text appears to the left of the anchor point
  */
 type LabelHorizontalPosition = 'left' | 'center' | 'right';
 /**
- * Cardinal direction anchor for positioning labels on geometry edges
- * Uses edge positions relative to the geometry's bounding box
- * Works for LineString, Polygon, and Circle geometries
- * - 'center': centroid/midpoint of the geometry
- * - 'top'/'right'/'bottom'/'left': edge positions
+ * Cardinal direction anchor for positioning labels on geometry edges.
+ *
+ * Uses edge positions relative to the geometry's bounding box.
+ * Works for LineString, Polygon, and Circle geometries:
+ * - `'center'`: centroid/midpoint of the geometry
+ * - `'top'`/`'right'`/`'bottom'`/`'left'`: edge positions based on bounding box
  */
 type CardinalLabelCoordinateAnchor = 'center' | 'top' | 'right' | 'bottom' | 'left';
 /**