@tomtom-org/maps-sdk 0.36.9 → 0.38.0

package/map/dist/index.d.ts

@@ -64,8 +64,9 @@ declare abstract class AbstractEventProxy {
      * @param sourceWithLayers The sources and layers to added.
      * @param handlerFn Function that will handle the event.
      * @param type Type of event to listen to.
+     * @param config Optional configuration for the event handler.
      */
-    addEventHandler<T = MapGeoJSONFeature>(sourceWithLayers: SourceWithLayers, handlerFn: UserEventHandler<T>, type: EventType): void;
+    addEventHandler<T = MapGeoJSONFeature>(sourceWithLayers: SourceWithLayers, handlerFn: UserEventHandler<T>, type: EventType, config: EventHandlerConfig | undefined): void;
     /**
      * Removes the given sources and layers from the interactive list. When not present, nothing happens.
      * @param type The event type to be removed.
@@ -103,7 +104,7 @@ declare abstract class AbstractEventProxy {
  * handling map style changes by restoring the module's state when needed.
  *
  * @typeParam SOURCES_WITH_LAYERS - The type defining the sources and layers used by this module
- * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed
+ * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed. When defined, must extend MapModuleCommonConfig.
  *
  * @example
  * ```typescript
@@ -117,7 +118,7 @@ declare abstract class AbstractEventProxy {
  *
  * @group Shared
  */
-export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends SourcesWithLayers, CFG = undefined> {
+export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends SourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> {
     private readonly sourceType;
     /**
      * @ignore
@@ -666,6 +667,7 @@ export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers
      * @ignore
      */
     protected _applyConfig(config: BaseMapModuleConfig | undefined): {
+        events?: EventHandlerConfig;
         visible?: boolean;
         layerGroupsVisibility?: BaseMapLayerGroupsVisibility;
     } | undefined;
@@ -825,7 +827,7 @@ export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers
  *
  * @group Base Map
  */
-export declare type BaseMapModuleConfig = {
+export declare type BaseMapModuleConfig = MapModuleCommonConfig & {
     /**
      * Controls the visibility of all layers associated with this module.
      *
@@ -964,7 +966,7 @@ export declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDP
 
 /**
  * Parameters to identify a feature by its ID or index in a given features array.
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type ByIdOrIndex = {
     /**
@@ -1118,7 +1120,7 @@ export declare type ChargingStopTextConfig = {
  * };
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type CleanEventStateOptions = ByIdOrIndex & {
     /**
@@ -1156,7 +1158,7 @@ export declare type CleanEventStateOptions = ByIdOrIndex & {
  * };
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type CleanEventStatesOptions = {
     /**
@@ -1203,7 +1205,7 @@ export declare type CleanEventStatesOptions = {
  * const rightClick: ClickEventType = 'contextmenu';
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type ClickEventType = 'click' | 'contextmenu';
 
@@ -1226,6 +1228,13 @@ declare const colorPalettes: {
     pastelRainbow: string[];
 };
 
+/**
+ * Allowed CSS cursor styles for map interactions.
+ *
+ * @group User Interaction Events
+ */
+export declare type CSSCursor = 'alias' | 'all-scroll' | 'auto' | 'cell' | 'context-menu' | 'col-resize' | 'copy' | 'crosshair' | 'default' | 'e-resize' | 'ew-resize' | 'grab' | 'grabbing' | 'help' | 'move' | 'n-resize' | 'ne-resize' | 'nesw-resize' | 'ns-resize' | 'nw-resize' | 'nwse-resize' | 'no-drop' | 'none' | 'not-allowed' | 'pointer' | 'progress' | 'row-resize' | 's-resize' | 'se-resize' | 'sw-resize' | 'text' | 'vertical-text' | 'w-resize' | 'wait' | 'zoom-in' | 'zoom-out';
+
 /**
  * Basic structure to define custom map icons, which end up in the map sprite.
  *
@@ -1919,6 +1928,47 @@ declare type DisplayTrafficSectionProps = DisplaySectionProps & TrafficSectionPr
     title?: string;
 };
 
+/**
+ * Optional events configuration for a map module.
+ *
+ * @group User Interaction Events
+ */
+export declare type EventHandlerConfig = EventHandlerCursorConfig;
+
+/**
+ * Event configuration options related to how the cursor appears during interactions.
+ *
+ * @group User Interaction Events
+ */
+export declare type EventHandlerCursorConfig = {
+    /**
+     * Optional configuration to show custom cursor when hovering over interactive features.
+     *
+     * @remarks
+     * Accepts any valid CSS cursor value.
+     *
+     * @default 'pointer'
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor | MDN cursor documentation}
+     *
+     * @example
+     * ```typescript
+     * // Default pointer
+     * cursorOnHover: 'pointer'
+     *
+     * // Crosshair for precise selection
+     * cursorOnHover: 'crosshair'
+     *
+     * // Help cursor for info bubbles
+     * cursorOnHover: 'help'
+     *
+     * // Custom cursor image
+     * cursorOnHover: 'url(/cursors/custom.png), pointer'
+     * ```
+     */
+    cursorOnHover?: CSSCursor;
+};
+
 declare type EventHandlers = Record<string, SourceEventHandlers>;
 
 /**
@@ -2012,12 +2062,13 @@ declare type EventHandlers = Record<string, SourceEventHandlers>;
  * });
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare class EventsModule<T = MapGeoJSONFeature> {
     private readonly eventProxy;
     private readonly sourceWithLayers;
-    constructor(eventProxy: EventsProxy, sourceWithLayers: SourceWithLayers);
+    private readonly config;
+    constructor(eventProxy: EventsProxy, sourceWithLayers: SourceWithLayers, config: EventHandlerConfig | undefined);
     /**
      * Register an event handler for user interactions with map features.
      *
@@ -2183,7 +2234,6 @@ export declare class EventsProxy extends AbstractEventProxy {
     private lastClickedSourceWithLayers?;
     private lastCursorStyle;
     private readonly config;
-    private readonly defaultZoomLevel;
     constructor(map: Map_2, config?: MapEventsConfig);
     private listenToEvents;
     enable(enabled: boolean): void;
@@ -2198,7 +2248,7 @@ export declare class EventsProxy extends AbstractEventProxy {
     private onMouseDown;
     private onMouseUp;
     private onMouseMove;
-    private updateCursor;
+    private updateHoverCursor;
     private onMapClick;
 }
 
@@ -2215,7 +2265,7 @@ export declare class EventsProxy extends AbstractEventProxy {
  * const hoverEvent: EventType = 'long-hover';
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type EventType = ClickEventType | HoverEventType;
 
@@ -2376,7 +2426,7 @@ export declare const FINISH_INDEX = "finish";
  *
  * @group Traffic Flow
  */
-export declare type FlowConfig = {
+export declare type FlowConfig = MapModuleCommonConfig & {
     /**
      * Controls the visibility of the traffic flow layers.
      *
@@ -2838,7 +2888,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
  *
  * @group Geometries
  */
-export declare type GeometriesModuleConfig = {
+export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
     /**
      * Fill color and opacity configuration.
      *
@@ -3345,7 +3395,7 @@ export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesW
  *
  * @group Hillshade
  */
-export declare type HillshadeModuleConfig = {
+export declare type HillshadeModuleConfig = MapModuleCommonConfig & {
     /**
      * Controls the visibility of the hillshade layers.
      *
@@ -3377,7 +3427,7 @@ declare type HillshadeSourcesWithLayers = {
  * const sustainedHover: HoverEventType = 'long-hover';
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type HoverEventType = 'hover' | 'long-hover';
 
@@ -3456,7 +3506,7 @@ export declare type IncidentsCommonConfig = {
  *
  * @group Traffic Incidents
  */
-export declare type IncidentsConfig = IncidentsCommonConfig & {
+export declare type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
     /**
      * Configuration specific to incident icon display.
      *
@@ -3543,9 +3593,57 @@ export declare const mapDisplayPoiCategoryMappings: Partial<Record<POICategory,
  * };
  * ```
  *
- * @group Map
+ * @group User Interaction Events
  */
-export declare type MapEventsConfig = {
+export declare type MapEventsConfig = EventHandlerCursorConfig & {
+    /**
+     * Optional configuration to show custom cursor when clicking (mouse down).
+     *
+     * @remarks
+     * Accepts any valid CSS cursor value. Provides visual feedback during the
+     * click action.
+     *
+     * @default 'grabbing'
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor | MDN cursor documentation}
+     *
+     * @example
+     * ```typescript
+     * // Grabbing hand
+     * cursorOnMouseDown: 'grabbing'
+     *
+     * // Move cursor
+     * cursorOnMouseDown: 'move'
+     *
+     * // Custom cursor
+     * cursorOnMouseDown: 'url(/cursors/drag.png), grabbing'
+     * ```
+     */
+    cursorOnMouseDown?: CSSCursor;
+    /**
+     * Optional configuration to show custom cursor on the map canvas when not interacting with any handled features.
+     *
+     * @remarks
+     * Accepts any valid CSS cursor value. This is the default cursor shown
+     * when not interacting with any features.
+     *
+     * @default 'default'
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor | MDN cursor documentation}
+     *
+     * @example
+     * ```typescript
+     * // Standard arrow
+     * cursorOnMap: 'default'
+     *
+     * // Open hand for draggable map
+     * cursorOnMap: 'grab'
+     *
+     * // Crosshair for measurement tools
+     * cursorOnMap: 'crosshair'
+     * ```
+     */
+    cursorOnMap?: CSSCursor;
     /**
      * Defines the event coordinates precision mode.
      *
@@ -3601,80 +3699,6 @@ export declare type MapEventsConfig = {
      * ```
      */
     paddingBoxPx?: number;
-    /**
-     * Optional configuration to show custom cursor when hovering over interactive features.
-     *
-     * @remarks
-     * Accepts any valid CSS cursor value.
-     *
-     * @default 'pointer'
-     *
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor | MDN cursor documentation}
-     *
-     * @example
-     * ```typescript
-     * // Default pointer
-     * cursorOnHover: 'pointer'
-     *
-     * // Crosshair for precise selection
-     * cursorOnHover: 'crosshair'
-     *
-     * // Help cursor for info bubbles
-     * cursorOnHover: 'help'
-     *
-     * // Custom cursor image
-     * cursorOnHover: 'url(/cursors/custom.png), pointer'
-     * ```
-     */
-    cursorOnHover?: string;
-    /**
-     * Optional configuration to show custom cursor when clicking (mouse down).
-     *
-     * @remarks
-     * Accepts any valid CSS cursor value. Provides visual feedback during the
-     * click action.
-     *
-     * @default 'grabbing'
-     *
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor | MDN cursor documentation}
-     *
-     * @example
-     * ```typescript
-     * // Grabbing hand
-     * cursorOnMouseDown: 'grabbing'
-     *
-     * // Move cursor
-     * cursorOnMouseDown: 'move'
-     *
-     * // Custom cursor
-     * cursorOnMouseDown: 'url(/cursors/drag.png), grabbing'
-     * ```
-     */
-    cursorOnMouseDown?: string;
-    /**
-     * Optional configuration to show custom cursor on the map canvas.
-     *
-     * @remarks
-     * Accepts any valid CSS cursor value. This is the default cursor shown
-     * when not interacting with any features.
-     *
-     * @default 'default'
-     *
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/cursor | MDN cursor documentation}
-     *
-     * @example
-     * ```typescript
-     * // Standard arrow
-     * cursorOnMap: 'default'
-     *
-     * // Open hand for draggable map
-     * cursorOnMap: 'grab'
-     *
-     * // Crosshair for measurement tools
-     * cursorOnMap: 'crosshair'
-     * ```
-     */
-    cursorOnMap?: string;
     /**
      * Delay to trigger a long-hover event when map has just moved (milliseconds).
      *
@@ -3803,9 +3827,20 @@ declare const mapFonts: readonly ["Noto-Regular", "NotoSans-MediumItalic", "Noto
  */
 export declare type MapLibreOptions = Omit<MapOptions, 'style' | 'attributionControl'>;
 
+/**
+ * Contains configuration options common to all map modules.
+ *
+ * @group Shared
+ */
+export declare type MapModuleCommonConfig = {
+    /**
+     * Optional configuration for user event handling that applies to this map module only.
+     */
+    events?: EventHandlerConfig;
+};
+
 /**
  * Whether a map module is based on a map style or on added GeoJSON data.
- * @ignore
  */
 declare type MapModuleSource = 'style' | 'geojson';
 
@@ -4484,8 +4519,8 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * ```typescript
      * import { search } from '@tomtom-international/maps-sdk-js/services';
      *
-     * const results = await search.search({ query: 'coffee' });
-     * await placesModule.show(results.results);
+     * const results = await search({ query: 'coffee' });
+     * await placesModule.show(results);
      * ```
      *
      * @example
@@ -4616,7 +4651,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
  *
  * @group Places
  */
-export declare type PlacesModuleConfig = {
+export declare type PlacesModuleConfig = MapModuleCommonConfig & {
     /**
      * Base style for all places.
      *
@@ -5298,7 +5333,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
  *
  * @group POIs
  */
-export declare type POIsModuleConfig = {
+export declare type POIsModuleConfig = MapModuleCommonConfig & {
     /**
      * Controls the visibility of the POI layers.
      *
@@ -5479,7 +5514,7 @@ export declare const preparePlacesForDisplay: (placesInput: Place | Place[] | Pl
  * };
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type PutEventStateOptions = ByIdOrIndex & {
     /**
@@ -6116,7 +6151,7 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
     /**
      * @ignore
      */
-    protected restoreDataAndConfigImpl(): Promise<void>;
+    protected restoreDataAndConfigImpl(): void;
     private addImageIfNotExisting;
     /**
      * Displays the given routes on the map.
@@ -6256,7 +6291,7 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
  *
  * @group Routing
  */
-export declare type RoutingModuleConfig = {
+export declare type RoutingModuleConfig = MapModuleCommonConfig & {
     /**
      * Units for displaying distances in route summaries and instructions.
      *
@@ -6393,6 +6428,7 @@ declare type SourceEventTypeHandler = {
     sourceWithLayers: SourceWithLayers;
     layerIDs: string[];
     fn: UserEventHandler<any>;
+    config?: EventHandlerConfig;
 };
 
 /**
@@ -6807,7 +6843,7 @@ export declare class StyleSourceWithLayers<SOURCE_SPEC extends SourceSpecificati
  * const normalProps: SupportsEvents = {};
  * ```
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type SupportsEvents = {
     /**
@@ -6967,7 +7003,7 @@ export declare type ToBeAddedLayerSpecWithoutSource<L extends LayerSpecification
  *       include: ['trafficFlow', 'trafficIncidents']
  *     },
  *     language: 'en-US',
- *     eventsConfig: {
+ *     events: {
  *       precisionMode: 'point-then-box',
  *       cursorOnHover: 'pointer'
  *     }
@@ -7103,7 +7139,7 @@ export declare class TomTomMap {
      *       include: ['trafficFlow', 'hillshade']
      *     },
      *     language: 'en-US',
-     *     eventsConfig: {
+     *     events: {
      *       precisionMode: 'point-then-box',
      *       paddingBoxPx: 10
      *     }
@@ -7118,7 +7154,7 @@ export declare class TomTomMap {
      * @see {@link https://maplibre.org/maplibre-gl-js-docs/api/map/ | MapLibre Map Parameters}
      * @see [Map Quickstart Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/quickstart)
      * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/map-styles)
-     * @see [User Events Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/user-events)
+     * @see [User Interaction Events Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/user-events)
      */
     constructor(mapLibreOptions: MapLibreOptions, mapParams?: Partial<TomTomMapParams>);
     private loadRTLTextPlugin;
@@ -7468,7 +7504,7 @@ export declare class TomTomMap {
  *   center: [4.9041, 52.3676],
  *   zoom: 12,
  *   style: 'standardLight',
- *   eventsConfig: {
+ *   events: {
  *     onClick: (event) => console.log('Map clicked', event)
  *   }
  * };
@@ -7505,7 +7541,7 @@ export declare type TomTomMapParams = GlobalConfig & {
      *
      * @example
      * ```typescript
-     * eventsConfig: {
+     * events: {
      *   onClick: (event) => {
      *     console.log('Clicked at', event.lngLat);
      *   },
@@ -7515,7 +7551,7 @@ export declare type TomTomMapParams = GlobalConfig & {
      * }
      * ```
      */
-    eventsConfig?: MapEventsConfig;
+    events?: MapEventsConfig;
 };
 
 /**
@@ -8352,7 +8388,7 @@ export declare const UNKNOWN_DELAY_COLOR = "#000000";
  *
  * @see {@link EventsModule.on} - For registering event handlers
  *
- * @group User Events
+ * @group User Interaction Events
  */
 export declare type UserEventHandler<T> = (topFeature: T, lngLat: LngLat, allEventFeatures: MapGeoJSONFeature[], sourceWithLayers: SourceWithLayers) => void;