@tomtom-org/maps-sdk 0.46.9 → 0.46.10

package/map/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Anything } from '@tomtom-org/maps-sdk/core';
+import { AreaAnalyticsMetricKey } from '@tomtom-org/maps-sdk/core';
+import { AreaAnalyticsMetricKey as AreaAnalyticsMetricKey_2 } from '@tomtom-org/maps-sdk/core';
 import { AreaAnalyticsMetrics } from '@tomtom-org/maps-sdk/core';
-import { AreaAnalyticsTileEntry } from '@tomtom-org/maps-sdk/core';
-import { AreaAnalyticsTimedEntry } from '@tomtom-org/maps-sdk/core';
 import { BackgroundLayerSpecification } from 'maplibre-gl';
 import { BBox } from '@tomtom-org/maps-sdk/core';
 import { BBox as BBox_2 } from '@tomtom-org/maps-sdk/core';
@@ -82,6 +82,16 @@ declare abstract class AbstractEventProxy {
      * @param config Optional configuration for the event handler.
      */
     addEventHandler<T = MapGeoJSONFeature>(sourceWithLayers: SourceWithLayers, handlerFn: UserEventHandler<T>, type: EventType, config: EventHandlerConfig | undefined): void;
+    /**
+     * Removes a single handler function for the given source and event type.
+     * Other handlers registered for the same source and type are not affected.
+     * Unlike {@link remove}, this does not remove the source from the interactive layer list —
+     * other handlers may still depend on it.
+     * @param sourceWithLayers The source whose handler should be removed.
+     * @param type The event type.
+     * @param handlerFn The exact function reference to remove.
+     */
+    removeHandler(sourceWithLayers: SourceWithLayers, type: EventType, handlerFn: UserEventHandler<any>): void;
     /**
      * Removes the given sources and layers from the interactive list. When not present, nothing happens.
      * @param type The event type to be removed.
@@ -163,6 +173,12 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
      * @ignore
      */
     protected _initializing: boolean;
+    /**
+     * Handlers registered via events.on('config-change', …).
+     * Stored here so the array reference stays stable across multiple events getter calls.
+     * @ignore
+     */
+    protected readonly configChangeHandlers: ((config: CFG | undefined) => void)[];
     /**
      * Indicates that this module is currently adding its sources and layers to the map, so during this time it might not function properly.
      * @see waitUntilModuleReady
@@ -219,6 +235,12 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
      * @see {@link getConfig} to retrieve the current configuration
      */
     applyConfig(config: CFG | undefined): void;
+    /**
+     * Emits a `config-change` event to all registered handlers.
+     * Skipped during module initialisation to avoid spurious events.
+     * @ignore
+     */
+    protected emitConfigChange(): void;
     /**
      * Internal implementation to apply config for the specific module.
      * @param config The config to apply. this.config contains the previous configuration (if any).
@@ -364,26 +386,245 @@ export declare class AddedSourceWithLayers<SOURCE_SPEC extends SourceSpecificati
 }
 
 /**
- * Preset color scheme for area analytics visualization.
+ * Default values for all {@link TrafficAreaAnalyticsConfig} options.
+ *
+ * Use these as a reference for what the module applies when a property is omitted,
+ * or spread them as a base when constructing a config programmatically.
+ *
+ * @group Traffic Area Analytics
+ */
+export declare const AREA_ANALYTICS_DEFAULTS: {
+    /** @see {@link TrafficAreaAnalyticsConfig.visible} */
+    visible: true;
+    /** @see {@link TrafficAreaAnalyticsConfig.displayMode} */
+    displayMode: "hexgrid-3d";
+    /** @see {@link TrafficAreaAnalyticsConfig.activeMetric} */
+    activeMetric: "congestionLevel";
+    /** @see {@link TrafficAreaAnalyticsConfig.metricConfig} */
+    metricConfig: {
+        congestionLevel: {
+            color: {
+                valueType: "raw";
+                stops: {
+                    value: number;
+                    color: string;
+                }[];
+            };
+            height: {
+                maxHeightMeters: number;
+                minHeightMeters: number;
+                scaleMode: "predefinedRange";
+            };
+        };
+        speed: {
+            color: {
+                valueType: "relativeToPredefinedRangePCT";
+                stops: {
+                    value: number;
+                    color: string;
+                }[];
+            };
+            height: {
+                maxHeightMeters: number;
+                minHeightMeters: number;
+                scaleMode: "predefinedRange";
+            };
+        };
+        travelTime: {
+            color: {
+                valueType: "relativeToPredefinedRangePCT";
+                stops: {
+                    value: number;
+                    color: string;
+                }[];
+            };
+            height: {
+                maxHeightMeters: number;
+                minHeightMeters: number;
+                scaleMode: "predefinedRange";
+            };
+        };
+        freeFlowSpeed: {
+            color: {
+                valueType: "relativeToPredefinedRangePCT";
+                stops: {
+                    value: number;
+                    color: string;
+                }[];
+            };
+            height: {
+                maxHeightMeters: number;
+                minHeightMeters: number;
+                scaleMode: "predefinedRange";
+            };
+        };
+        networkLength: {
+            color: {
+                valueType: "relativeToActualRangePCT";
+                stops: {
+                    value: number;
+                    color: string;
+                }[];
+            };
+            height: {
+                maxHeightMeters: number;
+                minHeightMeters: number;
+                scaleMode: "currentRange";
+            };
+        };
+    };
+    /** @see {@link AreaAnalyticsRegionPolygonConfig} */
+    regionPolygon: {
+        color: string;
+        fillOpacity: number;
+        outlineOpacity: number;
+        outlineWidth: number;
+        inverted: false;
+    };
+};
+
+/**
+ * Per-layer-type positioning configuration for area analytics layers.
+ *
+ * Controls where each analytics layer type sits in the map's layer stack independently.
+ * Each property accepts `'top'` (above all layers) or a well-known style layer ID.
+ * Omitted properties fall back to their default positions.
+ *
+ * @example
+ * ```typescript
+ * // Move all layers below the lowest label
+ * const config: TrafficAreaAnalyticsConfig = {
+ *   beforeLayerConfig: {
+ *     heatmap: 'lowestLabel',
+ *     hexgrid: { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
+ *     square:  { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
+ *   },
+ * };
+ *
+ * // Only reposition the heatmap layer
+ * const config: TrafficAreaAnalyticsConfig = {
+ *   beforeLayerConfig: { heatmap: 'top' },
+ * };
+ * ```
+ *
+ * @group Traffic Area Analytics
+ */
+export declare type AreaAnalyticsBeforeLayerConfig = {
+    /** Layer position for the heatmap layer. Defaults to `'lowestLabel'`. */
+    heatmap?: BeforeLayerConfig;
+    hexgrid?: {
+        /** Layer position for the flat hexgrid fill layer. Defaults to `'lowestLabel'`. */
+        flat2D?: BeforeLayerConfig;
+        /** Layer position for the extruded hexgrid layer. Defaults to `'lowestPlaceLabel'`. */
+        extrusion3D?: BeforeLayerConfig;
+    };
+    square?: {
+        /** Layer position for the flat square fill layer. Defaults to `'lowestLabel'`. */
+        flat2D?: BeforeLayerConfig;
+        /** Layer position for the extruded square layer. Defaults to `'lowestPlaceLabel'`. */
+        extrusion3D?: BeforeLayerConfig;
+    };
+};
+
+/**
+ * A single stop in an analytics color ramp.
+ *
+ * How `value` is interpreted depends on the surrounding `AreaAnalyticsColorStopsConfig.valueType`.
+ * `color` is any valid CSS color string.
+ *
+ * @group Traffic Area Analytics
+ */
+export declare type AreaAnalyticsColorStop = {
+    value: number;
+    color: string;
+};
+
+/**
+ * Custom color stops configuration with an explicit value-type hint.
+ *
+ * @example
+ * ```typescript
+ * // Stops whose values are actual congestion-level values (0–100)
+ * const color: AreaAnalyticsColorStopsConfig = {
+ *   valueType: 'raw',
+ *   stops: [
+ *     { value: 0,   color: '#2dc653' },
+ *     { value: 30,  color: '#f5a623' },
+ *     { value: 100, color: '#e03030' },
+ *   ],
+ * };
+ *
+ * // Stops as 0–100 % of the predefined metric range (speed: 0–120 km/h)
+ * const color: AreaAnalyticsColorStopsConfig = {
+ *   valueType: 'relativeToPredefinedRangePCT',
+ *   stops: [
+ *     { value: 0,   color: '#e03030' },  // 0 km/h
+ *     { value: 50,  color: '#f5a623' },  // 60 km/h
+ *     { value: 100, color: '#2dc653' },  // 120 km/h
+ *   ],
+ * };
+ *
+ * // Stops as 0–100 % of the live data range (maximum contrast regardless of absolute values)
+ * const color: AreaAnalyticsColorStopsConfig = {
+ *   valueType: 'relativeToActualRangePCT',
+ *   stops: [
+ *     { value: 0,   color: '#2dc653' },  // 0% = loaded minimum
+ *     { value: 50,  color: '#f5a623' },  // 50% = mid
+ *     { value: 100, color: '#e03030' },  // 100% = loaded maximum
+ *   ],
+ * };
+ * ```
+ *
+ * @group Traffic Area Analytics
+ */
+export declare type AreaAnalyticsColorStopsConfig = {
+    /**
+     * How stop values are interpreted. Defaults to `'raw'`.
+     */
+    valueType?: AreaAnalyticsValueType;
+    /**
+     * The color stops array.
+     */
+    stops: AreaAnalyticsColorStop[];
+};
+
+/**
+ * Preset color theme for area analytics visualization.
  *
- * - `'congestion'` — Green → amber → red (default, traffic-signal style)
- * - `'thermal'` — Blue → orange → red (heat-map style)
+ * - `'trafficLight'` — Green → amber → red (default, traffic-signal style)
+ * - `'heat'` — Blue → orange → red (heat-map style)
  * - `'monochrome'` — Light grey → dark grey (print-friendly)
+ * - `'viridis'` — Purple → blue → green → yellow (perceptually uniform, colorblind-safe)
+ * - `'plasma'` — Purple → magenta → orange → yellow (vivid, perceptually uniform)
+ *
+ * @group Traffic Area Analytics
+ */
+export declare type AreaAnalyticsColorTheme = 'trafficLight' | 'heat' | 'monochrome' | 'viridis' | 'plasma';
+
+/**
+ * Visualization mode for area analytics data.
+ *
+ * - `'hexgrid-3d'` — 3D extruded hexagonal cells colored and raised by metric value
+ * - `'hexgrid-2d'` — Flat hexagonal cells colored by metric value (no extrusion)
+ * - `'square-3d'` — 3D extruded square cells colored and raised by metric value
+ * - `'square-2d'` — Flat square cells colored by metric value (no extrusion)
+ * - `'heatmap'` — MapLibre density heatmap layer from tile centre points
  *
  * @group Traffic Area Analytics
  */
-export declare type AreaAnalyticsColorScheme = 'congestion' | 'thermal' | 'monochrome';
+export declare type AreaAnalyticsDisplayMode = 'heatmap' | 'hexgrid-3d' | 'hexgrid-2d' | 'square-3d' | 'square-2d';
 
 /**
  * Properties attached to each area analytics display feature.
  *
  * @remarks
  * Includes all optional metric fields from the API response plus a
- * stable `id` used by MapLibre's `promoteId` for event state tracking.
+ * stable `id` used by MapLibre's `promoteId` for event state tracking,
+ * and `eventState` (from `SupportsEvents`) used to drive hover/click styling.
  *
  * @group Traffic Area Analytics
  */
-export declare type AreaAnalyticsDisplayProperties = AreaAnalyticsMetrics & {
+export declare type AreaAnalyticsDisplayProperties = AreaAnalyticsMetrics & SupportsEvents & {
     /**
      * Stable feature identifier (typically the tile centre coordinates stringified
      * or the H3 cell index).
@@ -392,44 +633,174 @@ export declare type AreaAnalyticsDisplayProperties = AreaAnalyticsMetrics & {
 };
 
 /**
- * A single hex polygon feature for the hexgrid visualization.
+ * Height (extrusion) configuration for a metric.
+ *
+ * The shape depends on `scaleMode`:
+ * - `'predefinedRange'` / `'currentRange'` (default): use `maxHeightMeters` to set a true visual ceiling.
+ * - `'raw'`: use `scaleFactor` to multiply the raw metric value directly.
  *
  * @group Traffic Area Analytics
  */
-export declare type AreaAnalyticsHexFeature = Feature<Polygon, AreaAnalyticsDisplayProperties>;
+export declare type AreaAnalyticsHeightConfig = {
+    /**
+     * Normalised scale mode. The metric is mapped to a known range before computing height,
+     * so `maxHeightMeters` equals the actual maximum visual height in meters.
+     *
+     * @defaultValue 'predefinedRange'
+     */
+    scaleMode?: 'predefinedRange' | 'currentRange';
+    /**
+     * True visual maximum extrusion height in meters.
+     * The tallest cell reaches exactly this height.
+     *
+     * @defaultValue 1000
+     */
+    maxHeightMeters?: number;
+    /**
+     * Minimum extrusion height in meters.
+     *
+     * @defaultValue 0
+     */
+    minHeightMeters?: number;
+} | {
+    /** Raw scale mode: `scaleFactor` is multiplied directly with the raw metric value. */
+    scaleMode: 'raw';
+    /**
+     * Multiplier applied to the raw metric value to obtain extrusion height in meters.
+     *
+     * @defaultValue 1
+     */
+    scaleFactor?: number;
+    /**
+     * Minimum extrusion height in meters.
+     *
+     * @defaultValue 0
+     */
+    minHeightMeters?: number;
+};
 
 /**
- * Available metrics for area analytics visualization.
+ * Per-metric visualization configuration.
  *
  * @group Traffic Area Analytics
  */
-export declare type AreaAnalyticsMetricKey = 'congestionLevel' | 'speed' | 'travelTime';
+export declare type AreaAnalyticsMetricConfig = {
+    /**
+     * Color for this metric's visualization.
+     *
+     * Pass a preset theme name (`AreaAnalyticsColorTheme`) or a custom
+     * `AreaAnalyticsColorStopsConfig` object with explicit stop values and a
+     * value-type hint. For `speed`, the color order is automatically inverted
+     * so that slow speeds render as "bad" (red) and fast speeds as "good" (green).
+     *
+     * @defaultValue `'trafficLight'` theme
+     */
+    color?: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig;
+    /**
+     * Extrusion height configuration for this metric.
+     */
+    height?: AreaAnalyticsHeightConfig;
+    /**
+     * Filter visible tiles to only those within the given value range for this metric.
+     */
+    filters?: AreaAnalyticsMetricFilter;
+};
 
 /**
- * Visualization mode for area analytics data.
- *
- * - `'hexgrid'` — 3D extruded hexagonal cells colored and raised by metric value
- * - `'heatmap'` — MapLibre density heatmap layer from tile centre points
+ * Filter for visible tiles based on a metric's value range.
+ * Both `min` and `max` are optional; at least one should be provided to have effect.
  *
  * @group Traffic Area Analytics
  */
-export declare type AreaAnalyticsMode = 'heatmap' | 'hexgrid';
+export declare type AreaAnalyticsMetricFilter = {
+    /** Show only tiles where the metric is ≥ this value. */
+    min?: number;
+    /** Show only tiles where the metric is ≤ this value. */
+    max?: number;
+};
 
 /**
- * A single point feature for the heatmap visualization.
+ * Display configuration for the actual region boundary geometry.
+ *
+ * When area analytics data is shown, the original region polygon (the area
+ * the query was run for) is also rendered.  Use this config to control its
+ * appearance.
  *
  * @group Traffic Area Analytics
  */
-export declare type AreaAnalyticsPointFeature = Feature<Point, AreaAnalyticsDisplayProperties>;
+export declare type AreaAnalyticsRegionPolygonConfig = {
+    /**
+     * Color used for both the fill and outline of the region boundary.
+     *
+     * @defaultValue '#000000'
+     */
+    color?: string;
+    /**
+     * Opacity of the region fill.
+     *
+     * @defaultValue 0
+     */
+    fillOpacity?: number;
+    /**
+     * Opacity of the region outline.
+     *
+     * @defaultValue 0.5
+     */
+    outlineOpacity?: number;
+    /**
+     * Width of the region outline in pixels.
+     *
+     * @defaultValue 2
+     */
+    outlineWidth?: number;
+    /**
+     * When `true`, renders the region as an overlay covering everything *outside* the polygon
+     * boundary, effectively tinting the area outside the analytics region.
+     *
+     * Uses a world-minus-polygon donut geometry (same technique as the `GeometriesModule`
+     * `'inverted'` theme).
+     *
+     * @defaultValue false
+     */
+    inverted?: boolean;
+};
 
 /**
  * Sources and layers managed by this module.
+ * @ignore
  */
 declare type AreaAnalyticsSourcesWithLayers = {
     heatmap: GeoJSONSourceWithLayers<FeatureCollection<Point, AreaAnalyticsDisplayProperties>>;
     hexgrid: GeoJSONSourceWithLayers<FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>>;
+    square: GeoJSONSourceWithLayers<FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>>;
+    region: GeoJSONSourceWithLayers;
 };
 
+/**
+ * A single area analytics tile feature (point, hexagon, or square cell).
+ *
+ * @group Traffic Area Analytics
+ */
+export declare type AreaAnalyticsTileFeature = Feature<Point | Polygon, AreaAnalyticsDisplayProperties>;
+
+/**
+ * Determines how numeric `value` fields in color stops are interpreted.
+ *
+ * - `'raw'` — stop values are actual metric values used directly
+ *   (e.g. congestion: 0–100, speed: 0–120 km/h, travelTime: 0–20 s/km).
+ * - `'relativeToPredefinedRangePCT'` — stop values are 0–100 percentages relative to the SDK's predefined
+ *   metric ranges (congestion 0–100, speed 0–120 km/h, travelTime 0–20 s/km).
+ *   Useful for consistent coloring regardless of the current dataset.
+ * - `'relativeToActualRangePCT'` — stop values are 0–100 percentages relative to the live data
+ *   range actually present in the loaded tiles (0 % = loaded minimum, 100 % = loaded maximum).
+ *   Useful for maximum contrast when exact values are unknown.
+ *
+ * Defaults to `'raw'`.
+ *
+ * @group Traffic Area Analytics
+ */
+export declare type AreaAnalyticsValueType = 'raw' | 'relativeToPredefinedRangePCT' | 'relativeToActualRangePCT';
+
 /**
  * Availability level for POI icons with availability indicators.
  * @group Shared
@@ -834,50 +1205,26 @@ export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers
         layerGroups?: BaseMapLayerGroups;
     }): void;
     /**
-     * Gets the events interface for this module to handle user interactions.
-     *
-     * @returns An EventsModule instance for registering event handlers.
+     * Gets the unified events interface for this module, covering both user interactions
+     * and module lifecycle events.
      *
-     * @remarks
-     * **Supported Events:**
-     * - `click`: User clicks on a base map feature
-     * - `contextmenu`: User right-clicks on a feature
-     * - `hover`: Mouse enters a feature
-     * - `long-hover`: Mouse hovers over a feature for extended time
-     *
-     * **Event Handler Signature:**
-     * ```typescript
-     * (feature: MapGeoJSONFeature, lngLat: LngLat, allFeatures: MapGeoJSONFeature[]) => void
-     * ```
-     *
-     * @example
-     * Register click handler:
+     * **User interaction events** (`click`, `contextmenu`, `hover`, `long-hover`):
      * ```typescript
-     * baseMap.events.on('click', (feature, lngLat) => {
+     * const unsub = baseMap.events.on('click', (feature, lngLat) => {
      *   console.log('Clicked on:', feature.properties);
-     *   console.log('At coordinates:', lngLat);
      * });
+     * baseMap.events.off('hover'); // remove by type
      * ```
      *
-     * @example
-     * Multiple event types:
+     * **Module lifecycle events** (`config-change`):
      * ```typescript
-     * // Show tooltip on hover
-     * baseMap.events.on('hover', (feature) => {
-     *   showTooltip(feature.properties.name);
-     * });
-     *
-     * // Handle clicks
-     * baseMap.events.on('click', (feature) => {
-     *   selectFeature(feature.id);
+     * const unsub = baseMap.events.on('config-change', (config) => {
+     *   console.log('Config changed:', config);
      * });
-     *
-     * // Clean up
-     * baseMap.events.off('hover');
-     * baseMap.events.off('click');
+     * unsub(); // remove by returned function
      * ```
      */
-    get events(): EventsModule<MapGeoJSONFeature>;
+    get events(): CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfig, never>;
 }
 
 /**
@@ -1036,6 +1383,16 @@ declare type BaseSourceAndLayers = {
     vectorTiles: StyleSourceWithLayers;
 };
 
+/**
+ * Controls where a module's layers are placed in the map's layer stack.
+ *
+ * - `'top'` — renders above all other layers
+ * - A {@link MapStyleLayerID} — renders below the named style layer
+ *
+ * @group Shared
+ */
+export declare type BeforeLayerConfig = 'top' | MapStyleLayerID;
+
 /**
  * Builds the title of the place to display it on the map.
  * @param place The place to display.
@@ -1404,9 +1761,6 @@ export declare type CleanEventStatesOptions = {
  */
 export declare type ClickEventType = 'click' | 'contextmenu';
 
-/** @ignore */
-export declare const COLOR_SCHEMES: Record<AreaAnalyticsColorScheme, ColorStops>;
-
 export declare const colorPaletteIDs: ColorPaletteOptions[];
 
 export declare type ColorPaletteOptions = keyof typeof colorPalettes;
@@ -1428,12 +1782,126 @@ export declare const colorPalettes: {
     pastelRainbow: string[];
 };
 
-/** @ignore */
-declare type ColorStops = {
-    low: string;
-    mid: string;
-    high: string;
-};
+/**
+ * Unified events interface that blends user interaction events and module lifecycle events
+ * under a single `on` / `off` surface.
+ *
+ * User event types (`click`, `contextmenu`, `hover`, `long-hover`) are handled by the
+ * underlying {@link UserEvents} instance and removed with {@link off}.
+ *
+ * Module lifecycle event types (`config-change`, `shown-features`) are handled by the
+ * underlying {@link ModuleEvents} instance. Each `on` call returns an unsubscribe function.
+ * Both user and module event types are also removable in bulk via {@link off}.
+ *
+ * @typeParam T - Feature type surfaced by user interaction handlers.
+ * @typeParam CFG - Module configuration type passed to `config-change` handlers.
+ * @typeParam TShown - Data type passed to `shown-features` handlers. Use `never` for
+ *   modules that have no `show` method.
+ *
+ * @example
+ * ```typescript
+ * // User interaction
+ * const unsub = places.events.on('click', (feature, lngLat) => {
+ *   console.log('Clicked place:', feature.properties.name);
+ * });
+ *
+ * // Module lifecycle
+ * const unsubConfig = places.events.on('config-change', (config) => {
+ *   console.log('Config updated:', config);
+ * });
+ *
+ * const unsubShown = places.events.on('shown-features', (features) => {
+ *   console.log('Shown:', features);
+ * });
+ *
+ * // Cleanup
+ * unsub();
+ * unsubConfig();
+ * unsubShown();
+ * places.events.off('click'); // also valid for user events
+ * ```
+ *
+ * @group Events
+ */
+export declare class CombinedEvents<T, CFG, TShown = never> {
+    private readonly userEventsInstance;
+    private readonly moduleEventsInstance;
+    constructor(userEventsInstance: UserEvents<T>, moduleEventsInstance: ModuleEvents<CFG, TShown>);
+    /**
+     * Subscribe to a user interaction event (`click`, `contextmenu`, `hover`, `long-hover`).
+     *
+     * @param type - The user event type.
+     * @param handler - Called with the feature, click/hover coordinates, all features at the
+     *   point, and the source configuration.
+     * @returns An unsubscribe function. Call it to remove **only this handler**.
+     *
+     * @example
+     * ```typescript
+     * const unsub = places.events.on('click', (feature, lngLat) => {
+     *   showPlaceDetails(feature.properties);
+     * });
+     * unsub(); // remove only this handler
+     * ```
+     */
+    on(type: EventType, handler: UserEventHandler<T>): () => void;
+    /**
+     * Subscribe to config-change events.
+     *
+     * Fires after any configuration mutation — `applyConfig`, `setVisible`, or any
+     * module-specific setter. The handler receives the module's full updated configuration.
+     *
+     * @param type - `'config-change'`
+     * @param handler - Receives the module's config (or `undefined` when config is cleared).
+     * @returns An unsubscribe function. Call it to remove **only this handler**.
+     *
+     * @example
+     * ```typescript
+     * const unsub = trafficFlow.events.on('config-change', (config) => {
+     *   toggle.checked = config?.visible ?? false;
+     * });
+     * unsub();
+     * ```
+     */
+    on(type: 'config-change', handler: (config: CFG | undefined) => void): () => void;
+    /**
+     * Subscribe to shown-features events.
+     *
+     * Fires immediately after the module's `show()` method (or equivalent) has rendered
+     * new data on the map. Only available on modules that have a `show` method.
+     *
+     * @param type - `'shown-features'`
+     * @param handler - Receives the data that was passed to `show()`.
+     * @returns An unsubscribe function. Call it to remove **only this handler**.
+     *
+     * @example
+     * ```typescript
+     * const unsub = places.events.on('shown-features', (features) => {
+     *   fitMapToResults(features);
+     * });
+     * unsub();
+     * ```
+     */
+    on(type: 'shown-features', handler: (features: TShown) => void): () => void;
+    /**
+     * Remove **all** handlers for the given event type at once.
+     *
+     * Accepts both user interaction types (`click`, `contextmenu`, `hover`, `long-hover`) and
+     * module lifecycle types (`config-change`, `shown-features`).
+     *
+     * Prefer the unsubscribe function returned by {@link on} when you need to remove a single
+     * handler. Use `off` for bulk teardown — e.g. when unmounting a component that registered
+     * multiple handlers of the same type.
+     *
+     * @param type - The event type whose handlers should all be cleared.
+     *
+     * @example
+     * ```typescript
+     * places.events.off('click');          // clear all click handlers
+     * places.events.off('config-change');  // clear all config-change handlers
+     * ```
+     */
+    off(type: EventType | 'config-change' | 'shown-features'): void;
+}
 
 /**
  * Allowed CSS cursor styles for map interactions.
@@ -2284,398 +2752,135 @@ export declare type EventHandlerCursorConfig = {
 declare type EventHandlers = Record<string, SourceEventHandlers>;
 
 /**
- * Event handling interface for map features.
- *
- * Provides a simple API for attaching and removing event handlers for user interactions
- * with map features such as clicks, hovers, and context menus. Each map module (POIs, Routing,
- * Places, etc.) exposes an `events` property that returns an EventsModule instance.
- *
- * @typeParam T - The feature type returned in event handlers (extends MapGeoJSONFeature)
+ * This is the place where we handle the user events on the map (mousemove/hover and click mostly).
+ * To have full control on hovers and clicks when multiple overlapping layers are present, that logic must be centralized here.
+ * @ignore
+ */
+export declare class EventsProxy extends AbstractEventProxy {
+    private readonly map;
+    private readonly mapCanvas;
+    private enabled;
+    private hoveringLngLat?;
+    private hoveringPoint?;
+    private hoveringFeature?;
+    private hoveringFeatures?;
+    private hoveringSourceWithLayers?;
+    private longHoverTimeoutHandlerID?;
+    private firstDelayedHoverSinceMapMove;
+    private lastClickedFeature?;
+    private lastClickedSourceWithLayers?;
+    private lastCursorStyle;
+    private readonly config;
+    constructor(map: Map_2, config?: MapEventsConfig);
+    private listenToEvents;
+    enable(enabled: boolean): void;
+    private toPaddedBounds;
+    private isEnabled;
+    private getRenderedFeatures;
+    private clearLongHoverTimeout;
+    private restartLongHoverTimeout;
+    private handleLongHoverTimeout;
+    private onMouseStart;
+    private onMouseOut;
+    private onMouseDown;
+    private onMouseUp;
+    private onMouseMove;
+    private updateHoverCursor;
+    private onMapClick;
+}
+
+/**
+ * Type of user event supported by the SDK beyond basic MapLibre support.
  *
  * @remarks
- * **Supported Event Types:**
- * - `click`: User clicks/taps on a feature
- * - `contextmenu`: User right-clicks on a feature (or long-press on mobile)
- * - `hover`: Mouse enters a feature
- * - `long-hover`: Mouse hovers over feature for configured duration (300-800ms)
- *
- * **Event Handler Signature:**
- * ```typescript
- * (feature: T, lngLat: LngLat, features: T[]) => void
- * ```
- *
- * **Parameters:**
- * - `feature`: The primary feature under the cursor
- * - `lngLat`: Geographic coordinates of the event
- * - `features`: All features at this location (when multiple overlap)
- *
- * **Key Features:**
- * - Automatic cursor management (pointer on hover)
- * - Smart event handling for overlapping features
- * - Configurable hover delays
- * - Memory-safe cleanup when removing handlers
+ * The SDK extends MapLibre's basic event handling with additional event types
+ * that are commonly needed for interactive map features.
  *
  * @example
  * ```typescript
- * // POI click handler
- * const pois = map.pois();
- * pois.events.on('click', (feature, lngLat) => {
- *   console.log('Clicked POI:', feature.properties.name);
- *   console.log('Location:', lngLat);
- *   showInfoWindow(feature.properties);
- * });
+ * const eventType: EventType = 'click';
+ * const hoverEvent: EventType = 'long-hover';
+ * ```
  *
- * // Route waypoint hover
- * const routing = map.routing();
- * routing.events.waypoints.on('hover', (waypoint) => {
- *   showTooltip(`Waypoint ${waypoint.properties.index}`);
- * });
+ * @group User Interaction Events
+ */
+export declare type EventType = ClickEventType | HoverEventType;
+
+/**
+ * Extra properties to display color and title for a geometry on the map.
  *
- * // Long-hover for detailed info
- * pois.events.on('long-hover', (feature) => {
- *   loadAndShowDetailedInfo(feature.properties.id);
- * });
+ * Provides customization options for rendering polygon geometries, including
+ * visual styling and labeling.
  *
- * // Context menu (right-click)
- * routing.events.mainLines.on('contextmenu', (route, lngLat) => {
- *   showContextMenu(lngLat, [
- *     { label: 'Add waypoint here', action: () => addWaypoint(lngLat) },
- *     { label: 'View route details', action: () => showDetails(route) }
- *   ]);
- * });
+ * @remarks
+ * **Use Cases:**
+ * - Search result boundaries (e.g., city limits, postal codes)
+ * - Reachable range polygons
+ * - Delivery zones
+ * - Custom area highlights
  *
- * // Remove all click handlers
- * pois.events.off('click');
- * ```
+ * These properties override default styling and allow per-feature customization.
  *
  * @example
  * ```typescript
- * // Complete interaction example
- * const places = map.places();
- *
- * // Show name on hover
- * places.events.on('hover', (place) => {
- *   tooltip.show(place.properties.name);
- * });
- *
- * // Show details on click
- * places.events.on('click', (place, lngLat) => {
- *   sidebar.show({
- *     title: place.properties.name,
- *     address: place.properties.address.freeformAddress,
- *     coordinates: lngLat
- *   });
- * });
+ * const geometryProps: ExtraGeometryDisplayProps = {
+ *   title: 'Amsterdam City Center',
+ *   color: '#FF5733',
+ *   eventState: 'click'
+ * };
  *
- * // Cleanup on component unmount
- * onUnmount(() => {
- *   places.events.off('hover');
- *   places.events.off('click');
- * });
+ * // With custom properties
+ * const customProps: ExtraGeometryDisplayProps = {
+ *   title: 'Delivery Zone A',
+ *   color: '#00FF00',
+ *   zoneId: 'zone-a',
+ *   capacity: 100
+ * };
  * ```
  *
- * @group User Interaction Events
+ * @group Geometries
  */
-export declare class EventsModule<T = MapGeoJSONFeature> {
-    private readonly eventProxy;
-    private readonly sourceWithLayers;
-    private readonly config;
-    /**
-     * Optional function that transforms a raw {@link MapGeoJSONFeature} into the
-     * feature type `T` exposed by the module. When provided, every feature passed (fired)
-     * to event handlers is first run through this function, so callers receive the
-     * module's own feature shape instead of the underlying MapLibre feature.
-     *
-     * When omitted, `T` defaults to `MapGeoJSONFeature` and features are forwarded
-     * as-is.
-     */
-    private readonly mapping?;
-    constructor(eventProxy: EventsProxy, sourceWithLayers: SourceWithLayers, config: EventHandlerConfig | undefined, 
-    /**
-     * Optional function that transforms a raw {@link MapGeoJSONFeature} into the
-     * feature type `T` exposed by the module. When provided, every feature passed (fired)
-     * to event handlers is first run through this function, so callers receive the
-     * module's own feature shape instead of the underlying MapLibre feature.
-     *
-     * When omitted, `T` defaults to `MapGeoJSONFeature` and features are forwarded
-     * as-is.
-     */
-    mapping?: ((feature: MapGeoJSONFeature) => T) | undefined);
+export declare type ExtraGeometryDisplayProps = {
     /**
-     * Register an event handler for user interactions with map features.
-     *
-     * Attaches a callback function that will be invoked when users interact with
-     * features in this module (e.g., clicking on a POI, hovering over a route).
-     *
-     * @param type The type of event to listen for (click, contextmenu, hover, long-hover)
-     * @param handler Callback function invoked when the event occurs
+     * Display title for the geometry.
      *
      * @remarks
-     * **Handler Parameters:**
-     * - `feature`: The primary feature that triggered the event
-     * - `lngLat`: Geographic coordinates [longitude, latitude] of the event
-     * - `features`: Array of all features at the event location (for overlapping features)
-     *
-     * **Behavior:**
-     * - Only one handler per event type (calling `on()` again replaces the previous handler)
-     * - Handlers are preserved across map style changes
-     * - Cursor automatically changes to pointer on hover
-     * - Events respect module visibility (hidden features don't trigger events)
-     *
-     * **Performance:**
-     * - Hover events use spatial indexing for fast lookup
-     * - Long-hover has configurable delay to prevent accidental triggers
-     * - Event handlers should be lightweight to maintain smooth interaction
-     *
-     * @example
-     * ```typescript
-     * // Basic click handler
-     * module.events.on('click', (feature, lngLat, features) => {
-     *   console.log('Clicked feature:', feature.properties);
-     *   console.log('Location:', lngLat);
-     *   console.log('All features here:', features.length);
-     * });
-     *
-     * // Hover with tooltip
-     * module.events.on('hover', (feature) => {
-     *   const name = feature.properties.name || 'Unnamed';
-     *   tooltip.show(name);
-     * });
-     *
-     * // Long-hover for detailed preview
-     * module.events.on('long-hover', (feature) => {
-     *   // Only triggered after hovering for 300-800ms
-     *   loadPreview(feature.properties.id);
-     * });
+     * Optional text label displayed at the center of the polygon.
+     * If not provided, no label will be shown.
      *
-     * // Right-click context menu
-     * module.events.on('contextmenu', (feature, lngLat) => {
-     *   event.preventDefault(); // Prevent browser context menu
-     *   showCustomMenu(lngLat, feature);
-     * });
-     * ```
+     * **Common Uses:**
+     * - Area names (e.g., "Downtown", "Zone A")
+     * - Statistics (e.g., "30 min reachable")
+     * - Custom labels
      *
      * @example
      * ```typescript
-     * // Route-specific handlers
-     * const routing = map.routing();
-     *
-     * // Handle route line clicks
-     * routing.events.mainLines.on('click', (route) => {
-     *   highlightRoute(route.properties.routeID);
-     *   showRouteSummary(route.properties.summary);
-     * });
-     *
-     * // Handle waypoint interactions
-     * routing.events.waypoints.on('hover', (waypoint) => {
-     *   const index = waypoint.properties.index;
-     *   showTooltip(`Stop ${index + 1}`);
-     * });
+     * title: 'Amsterdam City Center'
+     * title: 'Zone A'
+     * title: '30 min driving range'
+     * title: undefined  // No label
      * ```
      */
-    on(type: EventType, handler: UserEventHandler<T>): void;
+    title?: string;
     /**
-     * Remove all event handlers for a specific event type.
-     *
-     * Unregisters the callback function for the specified event type, stopping
-     * further event notifications. This is important for cleanup to prevent
-     * memory leaks and unwanted behavior.
-     *
-     * @param type The type of event to stop listening for
+     * Fill color for the geometry.
      *
      * @remarks
-     * **Cleanup Behavior:**
-     * - Removes only the specified event type (other types remain active)
-     * - Resets cursor behavior for this module
-     * - Safe to call multiple times (no error if no handler exists)
-     * - Does not affect other modules' event handlers
-     *
-     * **When to Use:**
-     * - Component unmounting/cleanup
-     * - Switching between interaction modes
-     * - Temporarily disabling interactions
-     * - Replacing an existing handler (call `off()` then `on()`)
-     *
-     * **Best Practices:**
-     * - Always clean up event handlers when component unmounts
-     * - Remove handlers before removing features from the map
-     * - Use framework lifecycle hooks for automatic cleanup
-     *
-     * @example
-     * ```typescript
-     * // Remove click handlers
-     * module.events.off('click');
+     * Overrides the default fill color from the module configuration.
+     * Accepts any valid CSS color value.
      *
-     * // Remove all handlers
-     * module.events.off('click');
-     * module.events.off('hover');
-     * module.events.off('long-hover');
-     * module.events.off('contextmenu');
-     * ```
+     * **Color Formats:**
+     * - Hex: '#FF5733'
+     * - RGB: 'rgb(255, 87, 51)'
+     * - RGBA: 'rgba(255, 87, 51, 0.5)'
+     * - Named: 'red', 'blue', 'green'
      *
      * @example
      * ```typescript
-     * // React component cleanup
-     * useEffect(() => {
-     *   const pois = map.pois();
-     *
-     *   pois.events.on('click', handlePoiClick);
-     *   pois.events.on('hover', handlePoiHover);
-     *
-     *   return () => {
-     *     // Cleanup on unmount
-     *     pois.events.off('click');
-     *     pois.events.off('hover');
-     *   };
-     * }, [map]);
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Replace handler
-     * module.events.off('click'); // Remove old handler
-     * module.events.on('click', newHandler); // Add new handler
-     *
-     * // Disable interactions temporarily
-     * const savedHandler = currentHandler;
-     * module.events.off('click'); // Disable
-     * // ... later ...
-     * module.events.on('click', savedHandler); // Re-enable
-     * ```
-     */
-    off(type: EventType): void;
-}
-
-/**
- * This is the place where we handle the user events on the map (mousemove/hover and click mostly).
- * To have full control on hovers and clicks when multiple overlapping layers are present, that logic must be centralized here.
- * @ignore
- */
-export declare class EventsProxy extends AbstractEventProxy {
-    private readonly map;
-    private readonly mapCanvas;
-    private enabled;
-    private hoveringLngLat?;
-    private hoveringPoint?;
-    private hoveringFeature?;
-    private hoveringFeatures?;
-    private hoveringSourceWithLayers?;
-    private longHoverTimeoutHandlerID?;
-    private firstDelayedHoverSinceMapMove;
-    private lastClickedFeature?;
-    private lastClickedSourceWithLayers?;
-    private lastCursorStyle;
-    private readonly config;
-    constructor(map: Map_2, config?: MapEventsConfig);
-    private listenToEvents;
-    enable(enabled: boolean): void;
-    private toPaddedBounds;
-    private isEnabled;
-    private getRenderedFeatures;
-    private clearLongHoverTimeout;
-    private restartLongHoverTimeout;
-    private handleLongHoverTimeout;
-    private onMouseStart;
-    private onMouseOut;
-    private onMouseDown;
-    private onMouseUp;
-    private onMouseMove;
-    private updateHoverCursor;
-    private onMapClick;
-}
-
-/**
- * Type of user event supported by the SDK beyond basic MapLibre support.
- *
- * @remarks
- * The SDK extends MapLibre's basic event handling with additional event types
- * that are commonly needed for interactive map features.
- *
- * @example
- * ```typescript
- * const eventType: EventType = 'click';
- * const hoverEvent: EventType = 'long-hover';
- * ```
- *
- * @group User Interaction Events
- */
-export declare type EventType = ClickEventType | HoverEventType;
-
-/**
- * Extra properties to display color and title for a geometry on the map.
- *
- * Provides customization options for rendering polygon geometries, including
- * visual styling and labeling.
- *
- * @remarks
- * **Use Cases:**
- * - Search result boundaries (e.g., city limits, postal codes)
- * - Reachable range polygons
- * - Delivery zones
- * - Custom area highlights
- *
- * These properties override default styling and allow per-feature customization.
- *
- * @example
- * ```typescript
- * const geometryProps: ExtraGeometryDisplayProps = {
- *   title: 'Amsterdam City Center',
- *   color: '#FF5733',
- *   eventState: 'click'
- * };
- *
- * // With custom properties
- * const customProps: ExtraGeometryDisplayProps = {
- *   title: 'Delivery Zone A',
- *   color: '#00FF00',
- *   zoneId: 'zone-a',
- *   capacity: 100
- * };
- * ```
- *
- * @group Geometries
- */
-export declare type ExtraGeometryDisplayProps = {
-    /**
-     * Display title for the geometry.
-     *
-     * @remarks
-     * Optional text label displayed at the center of the polygon.
-     * If not provided, no label will be shown.
-     *
-     * **Common Uses:**
-     * - Area names (e.g., "Downtown", "Zone A")
-     * - Statistics (e.g., "30 min reachable")
-     * - Custom labels
-     *
-     * @example
-     * ```typescript
-     * title: 'Amsterdam City Center'
-     * title: 'Zone A'
-     * title: '30 min driving range'
-     * title: undefined  // No label
-     * ```
-     */
-    title?: string;
-    /**
-     * Fill color for the geometry.
-     *
-     * @remarks
-     * Overrides the default fill color from the module configuration.
-     * Accepts any valid CSS color value.
-     *
-     * **Color Formats:**
-     * - Hex: '#FF5733'
-     * - RGB: 'rgb(255, 87, 51)'
-     * - RGBA: 'rgba(255, 87, 51, 0.5)'
-     * - Named: 'red', 'blue', 'green'
-     *
-     * @example
-     * ```typescript
-     * color: '#FF5733'
-     * color: 'rgb(0, 128, 255)'
-     * color: 'rgba(255, 0, 0, 0.5)'
-     * color: 'red'
+     * color: '#FF5733'
+     * color: 'rgb(0, 128, 255)'
+     * color: 'rgba(255, 0, 0, 0.5)'
+     * color: 'red'
      * ```
      */
     color?: string;
@@ -2781,7 +2986,7 @@ export declare type FlowConfig = MapModuleCommonConfig & {
 export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
     shownFeatures: T;
     constructor(map: Map_2, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean);
-    show(featureCollection: T): void;
+    show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
     clear(): void;
     private findFeature;
     putEventState(options: PutEventStateOptions): void;
@@ -2907,6 +3112,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
     private titleSourceID;
     private titleLayerID;
     private lastRawInput;
+    private readonly shownFeaturesHandlers;
     /**
      * Make sure the map is ready before create an instance of the module and any other interaction with the map
      * @param tomtomMap The TomTomMap instance.
@@ -3143,7 +3349,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
     /**
      * Gets the events interface for handling user interactions with geometries.
      *
-     * @returns An EventsModule instance for registering event handlers.
+     * @returns A `UserEvents` instance for registering event handlers.
      *
      * @remarks
      * **Supported Events:**
@@ -3185,7 +3391,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * });
      * ```
      */
-    get events(): EventsModule<MapGeoJSONFeature>;
+    get events(): CombinedEvents<MapGeoJSONFeature, GeometriesModuleConfig, PolygonFeatures>;
 }
 
 /**
@@ -3355,7 +3561,7 @@ export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
  *
  * @group Geometries
  */
-export declare type GeometryBeforeLayerConfig = 'top' | MapStyleLayerID;
+export declare type GeometryBeforeLayerConfig = BeforeLayerConfig;
 
 /**
  * Color configuration for geometry fill styling.
@@ -3908,25 +4114,25 @@ export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesW
      */
     isVisible(): boolean;
     /**
-     * Gets the events interface for handling user interactions with hillshade.
-     *
-     * @returns An EventsModule instance for registering event handlers.
-     *
-     * @remarks
-     * **Supported Events:**
-     * - `click`: User clicks on the hillshade layer
-     * - `contextmenu`: User right-clicks
-     * - `hover`: Mouse enters hillshade area
-     * - `long-hover`: Extended hover
+     * Gets the unified events interface for this module, covering both user interactions
+     * and module lifecycle events.
      *
-     * @example
+     * **User interaction events** (`click`, `contextmenu`, `hover`, `long-hover`):
      * ```typescript
      * hillshade.events.on('click', (feature, lngLat) => {
      *   console.log('Clicked terrain at:', lngLat);
      * });
      * ```
+     *
+     * **Module lifecycle events** (`config-change`):
+     * ```typescript
+     * const unsub = hillshade.events.on('config-change', (config) => {
+     *   console.log('Hillshade config changed:', config);
+     * });
+     * unsub();
+     * ```
      */
-    get events(): EventsModule<MapGeoJSONFeature>;
+    get events(): CombinedEvents<MapGeoJSONFeature, HillshadeModuleConfig, never>;
 }
 
 /**
@@ -4581,6 +4787,107 @@ export declare const MINOR_DELAY_LABEL_COLOR = "#f58240";
  */
 export declare const MODERATE_DELAY_COLOR = "#FB2D09";
 
+/**
+ * Lifecycle event module for map modules.
+ *
+ * Provides a unified API for subscribing to module-level events that are not tied
+ * to user interaction with map features. Two event types are supported:
+ *
+ * - `config-change`: emitted whenever the module's configuration is updated
+ *   (via `applyConfig`, `resetConfig`, or any module-specific setter that mutates config).
+ * - `shown-features`: emitted by modules that have a `show` method, immediately after
+ *   features are displayed on the map.
+ *
+ * Each `on()` call returns an unsubscribe function so individual handlers can be
+ * removed without clearing the entire listener list.
+ *
+ * @typeParam TConfig - The module's configuration type.
+ * @typeParam TShownFeatures - The type of data passed to `show()`. Use `never` for
+ *   modules that have no `show` method.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribeConfig = trafficFlow.events.on('config-change', (config) => {
+ *   console.log('New config:', config);
+ * });
+ *
+ * const unsubscribeShown = places.events.on('shown-features', (features) => {
+ *   console.log('Shown:', features);
+ * });
+ *
+ * // Later:
+ * unsubscribeConfig();
+ * unsubscribeShown();
+ * ```
+ *
+ * @group Events
+ */
+export declare class ModuleEvents<TConfig, TShownFeatures = never> {
+    private readonly configChangeHandlers;
+    private readonly shownFeaturesHandlers;
+    constructor(configChangeHandlers: ((config: TConfig | undefined) => void)[], shownFeaturesHandlers: ((features: TShownFeatures) => void)[]);
+    /**
+     * Subscribe to config-change events.
+     *
+     * The handler is called with the module's full current configuration immediately after
+     * any mutation — whether through `applyConfig`, a module-specific setter, or `resetConfig`.
+     *
+     * @param type - `'config-change'`
+     * @param handler - Receives the module's config (or `undefined` when config is cleared).
+     * @returns An unsubscribe function. Call it to remove **only this handler** without
+     *   affecting other registered handlers for the same event type.
+     *
+     * @example
+     * ```typescript
+     * const unsub = trafficFlow.events.on('config-change', (config) => {
+     *   toggle.checked = config?.visible ?? false;
+     * });
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    on(type: 'config-change', handler: (config: TConfig | undefined) => void): () => void;
+    /**
+     * Subscribe to shown-features events.
+     *
+     * The handler is called immediately after a module's `show()` method (or equivalent)
+     * has updated the map with new data. Only available on modules that have a `show` method.
+     *
+     * @param type - `'shown-features'`
+     * @param handler - Receives the data that was passed to `show()`.
+     * @returns An unsubscribe function. Call it to remove **only this handler** without
+     *   affecting other registered handlers for the same event type.
+     *
+     * @example
+     * ```typescript
+     * const unsub = places.events.on('shown-features', (features) => {
+     *   fitMapToResults(features);
+     * });
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    on(type: 'shown-features', handler: (features: TShownFeatures) => void): () => void;
+    /**
+     * Remove **all** handlers for the given event type at once.
+     *
+     * Prefer the unsubscribe function returned by {@link on} when you need to remove a
+     * single handler. Use `off` for bulk teardown — e.g. when unmounting a component that
+     * registered multiple handlers.
+     *
+     * @param type - The event type whose handlers should all be cleared.
+     *
+     * @example
+     * ```typescript
+     * // Clear all config-change listeners in one call
+     * trafficFlow.events.off('config-change');
+     * ```
+     */
+    off(type: 'config-change' | 'shown-features'): void;
+}
+
 /**
  * @ignore
  */
@@ -4942,6 +5249,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      */
     private instanceIndex;
     private defaultPlaceIconID;
+    private readonly shownFeaturesHandlers;
     /**
      * Make sure the map is ready before create an instance of the module and any other interaction with the map
      * @param tomtomMap The TomTomMap instance.
@@ -5181,11 +5489,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * ```
      */
     cleanEventStates(options?: CleanEventStatesOptions): void;
-    /**
-     * Create the events on/off for this module
-     * @returns An instance of EventsModule
-     */
-    get events(): EventsModule<Place_2<DisplayPlaceProps>>;
+    get events(): CombinedEvents<Place_2<DisplayPlaceProps>, PlacesModuleConfig, Place_2 | Place_2[] | Places>;
 }
 
 /**
@@ -5859,7 +6163,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
     /**
      * Gets the events interface for handling user interactions with POIs.
      *
-     * @returns An EventsModule instance for registering event handlers.
+     * @returns A `UserEvents` instance for registering event handlers.
      *
      * @remarks
      * **Supported Events:**
@@ -5889,7 +6193,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
      * });
      * ```
      */
-    get events(): EventsModule<POIsModuleFeature>;
+    get events(): CombinedEvents<POIsModuleFeature, POIsModuleConfig, never>;
 }
 
 /**
@@ -6208,19 +6512,10 @@ export declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOption
 export declare type ReachableRangeLabelFn = (feature: PolygonFeature, index: number) => string;
 
 /**
- * Renders a day × hour congestion heatmap chart on a `<canvas>`.
- *
- * Treats `entries` as a flat sequential array (index 0 = day 0 hour 0,
- * index 1 = day 0 hour 1, etc.). Uses `startDate` to compute day labels.
- *
- * @param canvas - Target canvas element.
- * @param entries - Sequential hourly entries (168 = 7 days × 24 hours).
- * @param startDate - ISO date string (YYYY-MM-DD) for the first day.
- * @param colorScheme - Color scheme preset (default: `'congestion'`).
- *
- * @group Traffic Area Analytics
+ * Resolves the effective color stops for a given color configuration.
+ * @ignore
  */
-export declare function renderAreaAnalyticsChart(canvas: HTMLCanvasElement, entries: AreaAnalyticsTimedEntry[], startDate: string, colorScheme?: AreaAnalyticsColorScheme): void;
+export declare const resolveColorStops: (colorConfig: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig) => AreaAnalyticsColorStop[];
 
 /**
  * Available road hierarchy category identifiers.
@@ -6834,6 +7129,7 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
      * @private
      */
     private instanceIndex;
+    private readonly shownFeaturesHandlers;
     /**
      * Make sure the map is ready before create an instance of the module and any other interaction with the map
      * @param tomtomMap The TomTomMap instance.
@@ -7052,20 +7348,41 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
         summaryBubbles: DisplayRouteSummaries;
     };
     /**
-     * Create the events on/off for this module
-     * @returns An instance of EventsModule
+     * Unified events interface for the routing module, split into two namespaces:
+     *
+     * **`events.user`** — user interaction events, keyed by source:
+     * ```typescript
+     * routing.events.user.mainLines.on('click', (route) => { ... });
+     * routing.events.user.waypoints.on('hover', (waypoint) => { ... });
+     * ```
+     *
+     * **`events.module`** — module lifecycle events:
+     * ```typescript
+     * const unsub = routing.events.module.on('config-change', (config) => { ... });
+     * const unsub = routing.events.module.on('shown-features', (features) => {
+     *   if ('routes' in features) { ... }
+     * });
+     * unsub();
+     * ```
      */
     get events(): {
-        mainLines: EventsModule<Route<DisplayRouteProps>>;
-        waypoints: EventsModule<Waypoint<WaypointDisplayProps>>;
-        chargingStops: EventsModule<RouteSection>;
-        summaryBubbles: EventsModule<DisplayRouteSummary>;
-        incidents: EventsModule<RouteSection<DisplayTrafficSectionProps>>;
-        vehicleRestricted: EventsModule<RouteSection>;
-        ferries: EventsModule<RouteSection>;
-        tollRoads: EventsModule<RouteSection>;
-        tunnels: EventsModule<RouteSection>;
-        instructionLines: EventsModule<DisplayInstruction>;
+        user: {
+            mainLines: UserEvents<Route<DisplayRouteProps>>;
+            waypoints: UserEvents<Waypoint<WaypointDisplayProps>>;
+            chargingStops: UserEvents<RouteSection>;
+            summaryBubbles: UserEvents<DisplayRouteSummary>;
+            incidents: UserEvents<RouteSection<DisplayTrafficSectionProps>>;
+            vehicleRestricted: UserEvents<RouteSection>;
+            ferries: UserEvents<RouteSection>;
+            tollRoads: UserEvents<RouteSection>;
+            tunnels: UserEvents<RouteSection>;
+            instructionLines: UserEvents<DisplayInstruction>;
+        };
+        module: ModuleEvents<RoutingModuleConfig, {
+            routes: Route | Routes_2;
+        } | {
+            waypoints: PlanningWaypoint[] | Waypoints_2;
+        }>;
     };
     /**
      * Returns the map style layer under which route lines are rendered.
@@ -7205,6 +7522,22 @@ export declare const serviceRoadSubCategories: readonly ["parking", "driveway",
  */
 export declare type ServiceRoadSubCategory = (typeof serviceRoadSubCategories)[number];
 
+/**
+ * Options for the {@link GeoJSONSourceWithLayers.show} method.
+ * @ignore
+ */
+export declare type ShowOptions = {
+    /**
+     * When `true` (default), layer visibility is automatically set based on whether
+     * the feature collection is non-empty. Pass `false` from state-update calls
+     * (e.g. `putEventState`, `cleanEventState`) to avoid unintentionally hiding or
+     * showing layers when only feature state changes.
+     *
+     * @defaultValue true
+     */
+    automaticVisibility?: boolean;
+};
+
 /**
  * Optional parameters when showing routes on the map.
  *
@@ -7742,36 +8075,6 @@ export declare type SymbolLayerSpecWithoutSource = Omit<SymbolLayerSpecification
  */
 export declare const themedGeometryConfig: (palette?: ColorPaletteOptions, beforeLayerConfig?: GeometryBeforeLayerConfig) => GeometriesModuleConfig;
 
-/**
- * Converts area-analytics tile entries into a hexagonal polygon grid
- * using Turf's `hexGrid` and spatial-join aggregation.
- *
- * Tiles that fall within the same hexagon cell are averaged. Empty hexagons
- * (containing no tiles) are excluded from the result.
- *
- * @param tiles - Tile entries from the area analytics response.
- * @param cellSideKm - Hex cell side length in kilometres (default 0.5).
- * @returns A Polygon FeatureCollection with averaged metric properties.
- *
- * @group Traffic Area Analytics
- */
-export declare function tilesToHexFeatures(tiles: ReadonlyArray<AreaAnalyticsTileEntry>, cellSideKm?: number): FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
-
-/**
- * Converts an array of area-analytics tile entries into a GeoJSON
- * `FeatureCollection<Point>` suitable for the heatmap visualization layer.
- *
- * Each tile centre becomes a Point feature whose properties contain every
- * metric value returned by the API.
- *
- * @param tiles - Tile entries from `TrafficAreaAnalytics.features[0].properties.tiledData.tiles`.
- * @returns A Point FeatureCollection ready to pass to
- *          {@link TrafficAreaAnalyticsModule.show} as the `points` field.
- *
- * @group Traffic Area Analytics
- */
-export declare function tilesToPointFeatures(tiles: ReadonlyArray<AreaAnalyticsTileEntry>): FeatureCollection<Point, AreaAnalyticsDisplayProperties>;
-
 /**
  * @ignore
  */
@@ -8477,8 +8780,35 @@ export declare const TRAFFIC_INCIDENTS_SOURCE_ID = "vectorTilesIncidents";
  * Configuration for the Traffic Area Analytics visualization module.
  *
  * @remarks
- * Controls which visualization mode is active, which metric drives
- * the color/height, and overall layer visibility.
+ * The active metric is set via `activeMetric` (defaults to `'congestionLevel'`).
+ * Per-metric style settings (color, height, filters) are nested under `metricConfig` keyed by
+ * `AreaAnalyticsMetricKey`, making it easy to pre-configure multiple metrics independently and switch
+ * between them at runtime via `setMetric()`.
+ *
+ * @example
+ * ```typescript
+ * const config: TrafficAreaAnalyticsConfig = {
+ *   displayMode: 'hexgrid-3d',
+ *   activeMetric: 'congestionLevel',
+ *   metricConfig: {
+ *     congestionLevel: {
+ *       color: 'heat',
+ *       height: { maxHeightMeters: 80, scaleMode: 'predefinedRange' },
+ *       filters: { min: 10 },
+ *     },
+ *     speed: {
+ *       color: {
+ *         valueType: 'raw',
+ *         stops: [
+ *           { value: 0,   color: '#e03030' },
+ *           { value: 60,  color: '#f5a623' },
+ *           { value: 120, color: '#2dc653' },
+ *         ],
+ *       },
+ *     },
+ *   },
+ * };
+ * ```
  *
  * @group Traffic Area Analytics
  */
@@ -8492,37 +8822,54 @@ export declare type TrafficAreaAnalyticsConfig = MapModuleCommonConfig & {
     /**
      * Visualization mode.
      *
-     * @defaultValue 'hexgrid'
+     * @defaultValue 'hexgrid-3d'
      */
-    mode?: AreaAnalyticsMode;
+    displayMode?: AreaAnalyticsDisplayMode;
     /**
-     * The traffic metric that drives color and height.
+     * The metric that drives color and extrusion height.
      *
      * @defaultValue 'congestionLevel'
      */
-    metric?: AreaAnalyticsMetricKey;
+    activeMetric?: AreaAnalyticsMetricKey;
     /**
-     * Preset color scheme for the visualization layers.
+     * Per-metric visualization configuration (color, height, filters).
      *
-     * @defaultValue 'congestion'
+     * Metrics not listed here fall back to defaults (congestion color theme, metric-dependent height scale).
      */
-    colorScheme?: AreaAnalyticsColorScheme;
+    metricConfig?: Partial<Record<AreaAnalyticsMetricKey, AreaAnalyticsMetricConfig>>;
+    /**
+     * Per-layer-type positioning — controls where each analytics layer type sits in the map layer stack.
+     * Omitted layer types fall back to their default positions (`'lowestLabel'` for flat/heatmap, `'lowestPlaceLabel'` for extrusions).
+     */
+    beforeLayerConfig?: AreaAnalyticsBeforeLayerConfig;
+    /**
+     * Display options for the region polygon boundary drawn alongside the analytics data.
+     */
+    regionPolygon?: AreaAnalyticsRegionPolygonConfig;
 };
 
 /**
  * Traffic Area Analytics visualization module.
  *
- * Renders area-analytics data on the map in one of two modes:
- * - **hexgrid** — 3D extruded hexagonal polygons coloured and raised by the active metric
+ * Renders area-analytics data on the map in one of five modes:
+ * - **hexgrid-3d** — 3D extruded hexagonal cells coloured and raised by the active metric (default)
+ * - **hexgrid-2d** — Flat hexagonal cells coloured by the active metric
+ * - **square-3d** — 3D extruded square cells coloured and raised by the active metric
+ * - **square-2d** — Flat square cells coloured by the active metric
  * - **heatmap** — a MapLibre density-heatmap layer built from tile-centre points
  *
+ * The actual region boundary is always rendered alongside the analytics cells.
+ *
  * @remarks
  * **Quick start:**
  * ```typescript
  * import { TrafficAreaAnalyticsModule } from '@tomtom-org/maps-sdk/map';
  * import { trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
  *
- * const module = await TrafficAreaAnalyticsModule.get(map);
+ * const module = await TrafficAreaAnalyticsModule.get(map, {
+ *   displayMode: 'hexgrid-3d',
+ *   metric: { active: 'congestionLevel' },
+ * });
  * const analytics = await trafficAreaAnalytics({ ... });
  * await module.show(analytics);
  * ```
@@ -8531,34 +8878,51 @@ export declare type TrafficAreaAnalyticsConfig = MapModuleCommonConfig & {
  */
 export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
     private static lastInstanceIndex;
-    /** Named layer IDs for explicit access in paint updates. */
-    private heatmapLayerId;
-    private hexFillLayerId;
-    private hexExtrusionLayerId;
-    /** Cached for style-change restoration. */
+    private heatmapLayerSpec;
+    private hexFillLayerSpec;
+    private hexExtrusionLayerSpec;
+    private hexOutlineLayerSpec;
+    private hexExtrusionHighlightLayerSpec;
+    private squareFillLayerSpec;
+    private squareExtrusionLayerSpec;
+    private squareOutlineLayerSpec;
+    private squareExtrusionHighlightLayerSpec;
+    private regionFillLayerSpec;
+    private regionLineLayerSpec;
     private lastAnalytics;
+    private readonly shownFeaturesHandlers;
     /**
-     * Creates a new Traffic Area Analytics module.
+     * Creates and initialises a new Traffic Area Analytics module.
+     *
+     * All configuration properties are optional. When `config` is omitted (or only
+     * partially supplied), built-in defaults are applied for every missing field.
+     * After `get()` resolves, {@link TrafficAreaAnalyticsModule.getConfig} always returns a
+     * fully-populated configuration — there is no need to reference any default
+     * values yourself.
      *
      * @param tomtomMap - The TomTomMap instance.
-     * @param config - Optional initial configuration.
+     * @param config - Optional initial configuration. Omit to use all defaults.
      * @returns A promise that resolves with the initialised module.
      *
      * @example
      * ```typescript
-     * const module = await TrafficAreaAnalyticsModule.get(map, {
-     *   mode: 'hexgrid',
-     *   metric: 'congestionLevel',
+     * // No config needed — defaults are applied automatically.
+     * const module = await TrafficAreaAnalyticsModule.get(map);
+     * await module.show(analytics);
+     *
+     * // Or override specific properties while keeping everything else at default:
+     * const module = await TrafficAreaAnalyticsModule.get(map, {
+     *   displayMode: 'heatmap',
+     *   metricConfig: {
+     *     congestionLevel: { color: 'heat' },
+     *   },
      * });
      * ```
      */
     static get(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsConfig): Promise<TrafficAreaAnalyticsModule>;
     private constructor();
-    private get mode();
-    private get metric();
-    private get colorScheme();
     /** @ignore */
-    protected _initSourcesWithLayers(_config?: TrafficAreaAnalyticsConfig, restore?: boolean): AreaAnalyticsSourcesWithLayers;
+    protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, restore?: boolean): AreaAnalyticsSourcesWithLayers;
     /** @ignore */
     protected _applyConfig(config: TrafficAreaAnalyticsConfig | undefined): TrafficAreaAnalyticsConfig | undefined;
     /** @ignore */
@@ -8567,8 +8931,9 @@ export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAn
      * Displays area analytics data on the map.
      *
      * Accepts the raw response from `trafficAreaAnalytics()`. Tile data is
-     * transformed internally to point features (heatmap) and hexagonal
-     * polygons (hexgrid) — no manual data preparation is needed.
+     * transformed internally to point features (heatmap), hexagonal polygons
+     * (hexgrid modes), and square polygons (square modes).
+     * The region boundary geometry is also displayed.
      *
      * @param analytics - The raw `TrafficAreaAnalytics` service response.
      *
@@ -8586,49 +8951,149 @@ export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAn
     /**
      * Switches the visualisation mode.
      *
-     * @param mode - `'heatmap'` or `'hexgrid'`.
+     * @param mode - One of `'heatmap'`, `'hexgrid-3d'`, `'hexgrid-2d'`, `'square-3d'`, `'square-2d'`.
      */
-    setMode(mode: AreaAnalyticsMode): void;
+    setMode(mode: AreaAnalyticsDisplayMode): void;
     /**
      * Changes the active metric that drives colour and height.
      *
-     * @param metric - One of `'congestionLevel'`, `'speed'`, or `'travelTime'`.
+     * Updates `activeMetric` in the config to the given metric key.
+     *
+     * @param metric - One of `'congestionLevel'`, `'speed'`, `'travelTime'`, `'freeFlowSpeed'`, or `'networkLength'`.
      */
-    setMetric(metric: AreaAnalyticsMetricKey): void;
+    setMetric(metric: AreaAnalyticsMetricKey_2): void;
     /**
-     * Changes the color scheme preset.
+     * Sets the color for one or more metrics.
+     *
+     * Pass a preset theme name or a custom color-stops configuration.
+     * Pass `undefined` to clear the color override for the targeted metrics.
+     *
+     * @param color - A preset theme, an `AreaAnalyticsColorStopsConfig`, or `undefined` to clear.
+     * @param metrics - Optional list of metrics to target.
+     *   When omitted, the color is applied to **all** metrics.
+     *
+     * @example
+     * ```typescript
+     * // Apply a theme to all metrics
+     * module.setColor('heat');
+     *
+     * // Apply a theme to specific metrics only
+     * module.setColor('heat', ['speed', 'freeFlowSpeed']);
+     *
+     * // Apply custom stops to a single metric
+     * module.setColor(
+     *   { valueType: 'raw', stops: [{ value: 0, color: '#2dc653' }, { value: 100, color: '#e03030' }] },
+     *   ['congestionLevel'],
+     * );
+     *
+     * // Clear color override for all metrics
+     * module.setColor(undefined);
      *
-     * @param scheme - One of `'congestion'`, `'thermal'`, or `'monochrome'`.
+     * // Clear color override for a specific metric
+     * module.setColor(undefined, ['speed']);
+     * ```
      */
-    setColorScheme(scheme: AreaAnalyticsColorScheme): void;
+    setColor(color: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig | undefined, metrics?: AreaAnalyticsMetricKey_2[]): void;
+    /**
+     * Configures extrusion height behaviour for one or more metrics.
+     *
+     * @param heightConfig - Height configuration.
+     * @param metrics - Optional list of metrics to target.
+     *   When omitted, the height config is applied to **all** metrics.
+     *
+     * @example
+     * ```typescript
+     * // Apply to all metrics
+     * module.setHeight({ maxHeightMeters: 100, minHeightMeters: 5 });
+     *
+     * // Apply only to specific metrics
+     * module.setHeight({ scaleMode: 'currentRange', maxHeightMeters: 500 }, ['speed', 'freeFlowSpeed']);
+     * ```
+     */
+    setHeight(heightConfig: AreaAnalyticsHeightConfig, metrics?: AreaAnalyticsMetricKey_2[]): void;
+    /**
+     * Filters visible tiles by value range for one or more metrics.
+     *
+     * @param filter - Filter config. Pass `undefined` to clear.
+     * @param metrics - Optional list of metrics to target.
+     *   When omitted, the filter is applied to **all** metrics.
+     *
+     * @example
+     * ```typescript
+     * // Filter all metrics
+     * module.filter({ min: 20, max: 80 });
+     *
+     * // Filter only a specific metric
+     * module.filter({ min: 50 }, ['congestionLevel']);
+     *
+     * // Clear filter for all metrics
+     * module.filter(undefined);
+     * ```
+     */
+    filter(filter?: AreaAnalyticsMetricFilter, metrics?: AreaAnalyticsMetricKey_2[]): void;
+    /**
+     * Clears any active tile filter for one or more metrics.
+     *
+     * @param metrics - Optional list of metrics to clear. When omitted, clears filters for **all** metrics.
+     */
+    clearFilter(metrics?: AreaAnalyticsMetricKey_2[]): void;
     /**
      * Shows or hides all area analytics layers.
      */
     setVisible(visible: boolean): void;
     /**
-     * Whether any area analytics layer is currently visible.
+     * Whether any area analytics (data) layer is currently visible.
      */
     isVisible(): boolean;
     /**
-     * Returns the currently displayed data for both visualisation modes.
+     * Returns the currently displayed data for all visualisation modes.
      */
     getShown(): {
         heatmap: FeatureCollection<Point, AreaAnalyticsDisplayProperties>;
         hexgrid: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
+        square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
     };
     /**
-     * Event interface for the hexgrid layer (hover / click on hexagonal cells).
+     * Repositions analytics layers independently by layer type.
+     *
+     * Only the properties present in `layerConfig` are repositioned; omitted layer types are left in place.
+     *
+     * @param layerConfig - Per-layer-type positioning config. Each value is `'top'` or a `MapStyleLayerID`.
+     */
+    moveBeforeLayer(layerConfig: AreaAnalyticsBeforeLayerConfig): void;
+    /**
+     * Event interface for the hexgrid and square layers.
+     *
+     * Supports feature-interaction events (`hover`, `click`, `contextmenu`, `long-hover`) as well
+     * as module lifecycle events (`config-change`, `shown-features`) — all through the same
+     * `events.on(type, handler)` surface.
      *
      * @example
      * ```typescript
      * module.events.on('hover', (feature, lngLat) => {
      *   console.log(feature.properties.congestionLevel);
      * });
+     *
+     * const unsub = module.events.on('config-change', (config) => {
+     *   console.log('Config updated:', config);
+     * });
+     *
+     * module.events.on('shown-features', (data) => {
+     *   console.log('Analytics data shown:', data);
+     * });
      * ```
      */
-    get events(): EventsModule<AreaAnalyticsHexFeature>;
+    get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsConfig, TrafficAreaAnalytics>;
+    private get mode();
+    private get activeMetric();
     private applyModeVisibility;
-    private applyMetricToLayers;
+    private hideAllDataLayers;
+    private addHighlightLayersToMap;
+    private setHighlightLayerVisible;
+    private applyLayerConfig;
+    private applyRegionConfig;
+    private applyFiltersToLayers;
+    private buildRegionFC;
 }
 
 /**
@@ -8985,11 +9450,7 @@ export declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSour
     getShown(): {
         trafficFlow: TrafficFlowModuleFeature[];
     };
-    /**
-     * Create the events on/off for this module
-     * @returns An instance of EventsModule
-     */
-    get events(): EventsModule<TrafficFlowModuleFeature>;
+    get events(): CombinedEvents<TrafficFlowModuleFeature, FlowConfig, never>;
 }
 
 /**
@@ -9481,11 +9942,7 @@ export declare class TrafficIncidentsModule extends AbstractMapModule<TrafficInc
     getShown(): {
         trafficIncidents: TrafficIncidentsModuleFeature[];
     };
-    /**
-     * Create the events on/off for this module
-     * @returns An instance of EventsModule
-     */
-    get events(): EventsModule<TrafficIncidentsModuleFeature>;
+    get events(): CombinedEvents<TrafficIncidentsModuleFeature, IncidentsConfig, never>;
 }
 
 /**
@@ -9593,12 +10050,282 @@ export declare const UNKNOWN_DELAY_COLOR = "#000000";
  * });
  * ```
  *
- * @see {@link EventsModule.on} - For registering event handlers
+ * @see {@link UserEvents.on} - For registering event handlers
  *
  * @group User Interaction Events
  */
 export declare type UserEventHandler<T> = (topFeature: T, lngLat: LngLat, allEventFeatures: MapGeoJSONFeature[], sourceWithLayers: SourceWithLayers) => void;
 
+/**
+ * Event handling interface for map features.
+ *
+ * Provides a simple API for attaching and removing event handlers for user interactions
+ * with map features such as clicks, hovers, and context menus. Each map module (POIs, Routing,
+ * Places, etc.) exposes an `events` property that returns a `UserEvents` instance.
+ *
+ * @typeParam T - The feature type returned in event handlers (extends MapGeoJSONFeature)
+ *
+ * @remarks
+ * **Supported Event Types:**
+ * - `click`: User clicks/taps on a feature
+ * - `contextmenu`: User right-clicks on a feature (or long-press on mobile)
+ * - `hover`: Mouse enters a feature
+ * - `long-hover`: Mouse hovers over feature for configured duration (300-800ms)
+ *
+ * **Event Handler Signature:**
+ * ```typescript
+ * (feature: T, lngLat: LngLat, features: T[]) => void
+ * ```
+ *
+ * **Parameters:**
+ * - `feature`: The primary feature under the cursor
+ * - `lngLat`: Geographic coordinates of the event
+ * - `features`: All features at this location (when multiple overlap)
+ *
+ * **Key Features:**
+ * - Automatic cursor management (pointer on hover)
+ * - Smart event handling for overlapping features
+ * - Configurable hover delays
+ * - Memory-safe cleanup when removing handlers
+ *
+ * @example
+ * ```typescript
+ * // POI click handler
+ * const pois = map.pois();
+ * pois.events.on('click', (feature, lngLat) => {
+ *   console.log('Clicked POI:', feature.properties.name);
+ *   console.log('Location:', lngLat);
+ *   showInfoWindow(feature.properties);
+ * });
+ *
+ * // Route waypoint hover
+ * const routing = map.routing();
+ * routing.events.waypoints.on('hover', (waypoint) => {
+ *   showTooltip(`Waypoint ${waypoint.properties.index}`);
+ * });
+ *
+ * // Long-hover for detailed info
+ * pois.events.on('long-hover', (feature) => {
+ *   loadAndShowDetailedInfo(feature.properties.id);
+ * });
+ *
+ * // Context menu (right-click)
+ * routing.events.mainLines.on('contextmenu', (route, lngLat) => {
+ *   showContextMenu(lngLat, [
+ *     { label: 'Add waypoint here', action: () => addWaypoint(lngLat) },
+ *     { label: 'View route details', action: () => showDetails(route) }
+ *   ]);
+ * });
+ *
+ * // Remove all click handlers
+ * pois.events.off('click');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Complete interaction example
+ * const places = map.places();
+ *
+ * // Show name on hover
+ * places.events.on('hover', (place) => {
+ *   tooltip.show(place.properties.name);
+ * });
+ *
+ * // Show details on click
+ * places.events.on('click', (place, lngLat) => {
+ *   sidebar.show({
+ *     title: place.properties.name,
+ *     address: place.properties.address.freeformAddress,
+ *     coordinates: lngLat
+ *   });
+ * });
+ *
+ * // Cleanup on component unmount
+ * onUnmount(() => {
+ *   places.events.off('hover');
+ *   places.events.off('click');
+ * });
+ * ```
+ *
+ * @group Events
+ */
+export declare class UserEvents<T = MapGeoJSONFeature> {
+    private readonly eventProxy;
+    private readonly config;
+    /**
+     * Optional function that transforms a raw {@link MapGeoJSONFeature} into the
+     * feature type `T` exposed by the module. When provided, every feature passed (fired)
+     * to event handlers is first run through this function, so callers receive the
+     * module's own feature shape instead of the underlying MapLibre feature.
+     *
+     * When omitted, `T` defaults to `MapGeoJSONFeature` and features are forwarded
+     * as-is.
+     */
+    private readonly mapping?;
+    private readonly sources;
+    constructor(eventProxy: EventsProxy, 
+    /**
+     * The source(s) whose features this module handles events for.
+     * Pass an array to register handlers across multiple sources representing similar data in different display modes (e.g. hexgrid + square
+     * in {@link TrafficAreaAnalyticsModule}). A single value is also accepted for
+     * backwards compatibility.
+     */
+    sourcesWithLayers: SourceWithLayers | SourceWithLayers[], config: EventHandlerConfig | undefined, 
+    /**
+     * Optional function that transforms a raw {@link MapGeoJSONFeature} into the
+     * feature type `T` exposed by the module. When provided, every feature passed (fired)
+     * to event handlers is first run through this function, so callers receive the
+     * module's own feature shape instead of the underlying MapLibre feature.
+     *
+     * When omitted, `T` defaults to `MapGeoJSONFeature` and features are forwarded
+     * as-is.
+     */
+    mapping?: ((feature: MapGeoJSONFeature) => T) | undefined);
+    /**
+     * Register an event handler for user interactions with map features.
+     *
+     * Attaches a callback function that will be invoked when users interact with
+     * features in this module (e.g., clicking on a POI, hovering over a route).
+     *
+     * @param type The type of event to listen for (click, contextmenu, hover, long-hover)
+     * @param handler Callback function invoked when the event occurs
+     *
+     * @remarks
+     * **Handler Parameters:**
+     * - `feature`: The primary feature that triggered the event
+     * - `lngLat`: Geographic coordinates [longitude, latitude] of the event
+     * - `features`: Array of all features at the event location (for overlapping features)
+     *
+     * **Behavior:**
+     * - Only one handler per event type (calling `on()` again replaces the previous handler)
+     * - Handlers are preserved across map style changes
+     * - Cursor automatically changes to pointer on hover
+     * - Events respect module visibility (hidden features don't trigger events)
+     *
+     * **Performance:**
+     * - Hover events use spatial indexing for fast lookup
+     * - Long-hover has configurable delay to prevent accidental triggers
+     * - Event handlers should be lightweight to maintain smooth interaction
+     *
+     * @example
+     * ```typescript
+     * // Basic click handler
+     * module.events.on('click', (feature, lngLat, features) => {
+     *   console.log('Clicked feature:', feature.properties);
+     *   console.log('Location:', lngLat);
+     *   console.log('All features here:', features.length);
+     * });
+     *
+     * // Hover with tooltip
+     * module.events.on('hover', (feature) => {
+     *   const name = feature.properties.name || 'Unnamed';
+     *   tooltip.show(name);
+     * });
+     *
+     * // Long-hover for detailed preview
+     * module.events.on('long-hover', (feature) => {
+     *   // Only triggered after hovering for 300-800ms
+     *   loadPreview(feature.properties.id);
+     * });
+     *
+     * // Right-click context menu
+     * module.events.on('contextmenu', (feature, lngLat) => {
+     *   event.preventDefault(); // Prevent browser context menu
+     *   showCustomMenu(lngLat, feature);
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Route-specific handlers
+     * const routing = map.routing();
+     *
+     * // Handle route line clicks
+     * routing.events.mainLines.on('click', (route) => {
+     *   highlightRoute(route.properties.routeID);
+     *   showRouteSummary(route.properties.summary);
+     * });
+     *
+     * // Handle waypoint interactions
+     * routing.events.waypoints.on('hover', (waypoint) => {
+     *   const index = waypoint.properties.index;
+     *   showTooltip(`Stop ${index + 1}`);
+     * });
+     * ```
+     */
+    on(type: EventType, handler: UserEventHandler<T>): () => void;
+    /**
+     * Remove all event handlers for a specific event type.
+     *
+     * Unregisters the callback function for the specified event type, stopping
+     * further event notifications. This is important for cleanup to prevent
+     * memory leaks and unwanted behavior.
+     *
+     * @param type The type of event to stop listening for
+     *
+     * @remarks
+     * **Cleanup Behavior:**
+     * - Removes only the specified event type (other types remain active)
+     * - Resets cursor behavior for this module
+     * - Safe to call multiple times (no error if no handler exists)
+     * - Does not affect other modules' event handlers
+     *
+     * **When to Use:**
+     * - Component unmounting/cleanup
+     * - Switching between interaction modes
+     * - Temporarily disabling interactions
+     * - Replacing an existing handler (call `off()` then `on()`)
+     *
+     * **Best Practices:**
+     * - Always clean up event handlers when component unmounts
+     * - Remove handlers before removing features from the map
+     * - Use framework lifecycle hooks for automatic cleanup
+     *
+     * @example
+     * ```typescript
+     * // Remove click handlers
+     * module.events.off('click');
+     *
+     * // Remove all handlers
+     * module.events.off('click');
+     * module.events.off('hover');
+     * module.events.off('long-hover');
+     * module.events.off('contextmenu');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // React component cleanup
+     * useEffect(() => {
+     *   const pois = map.pois();
+     *
+     *   pois.events.on('click', handlePoiClick);
+     *   pois.events.on('hover', handlePoiHover);
+     *
+     *   return () => {
+     *     // Cleanup on unmount
+     *     pois.events.off('click');
+     *     pois.events.off('hover');
+     *   };
+     * }, [map]);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Replace handler
+     * module.events.off('click'); // Remove old handler
+     * module.events.on('click', newHandler); // Add new handler
+     *
+     * // Disable interactions temporarily
+     * const savedHandler = currentHandler;
+     * module.events.off('click'); // Disable
+     * // ... later ...
+     * module.events.on('click', savedHandler); // Re-enable
+     * ```
+     */
+    off(type: EventType): void;
+}
+
 /**
  * Generic filter configuration for showing or hiding items by value.
  *