@tomtom-org/maps-sdk 0.47.0 → 0.47.2

package/map/dist/index.d.ts

@@ -54,8 +54,10 @@ import { SourceSpecification } from 'maplibre-gl';
 import { StyleSpecification } from 'maplibre-gl';
 import { SymbolLayerSpecification } from 'maplibre-gl';
 import { TrafficAreaAnalytics } from '@tomtom-org/maps-sdk/core';
+import { TrafficIncident } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentBaseProperties } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentCategory } from '@tomtom-org/maps-sdk/core';
+import { TrafficIncidentDetails } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentTimeValidity } from '@tomtom-org/maps-sdk/core';
 import { TrafficSectionProps } from '@tomtom-org/maps-sdk/core';
 import { Waypoint } from '@tomtom-org/maps-sdk/core';
@@ -1204,6 +1206,7 @@ export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers
     setVisible(visible: boolean, options?: {
         layerGroups?: BaseMapLayerGroups;
     }): void;
+    private _setVisible;
     /**
      * Gets the unified events interface for this module, covering both user interactions
      * and module lifecycle events.
@@ -1379,6 +1382,18 @@ export declare type BaseMapModuleInitConfig = BaseMapModuleConfig & {
     layerGroupsFilter?: BaseMapLayerGroups;
 };
 
+/**
+ * The deduplicated set of base-map POI categories — the right-hand side of
+ * {@link completeMapDisplayPoiCategoryMappings}. Each value names the
+ * `poi-<value>` sprite the base-map style ships, so this set is what callers
+ * (e.g., the `pin-clustered` cluster pin's `match` expression) statically
+ * enumerate when they need MapLibre to pre-load every possible sprite into
+ * the atlas.
+ *
+ * @ignore
+ */
+export declare const baseMapPOICategoryValues: readonly string[];
+
 declare type BaseSourceAndLayers = {
     vectorTiles: StyleSourceWithLayers;
 };
@@ -1903,6 +1918,22 @@ export declare class CombinedEvents<T, CFG, TShown = never> {
     off(type: EventType | 'config-change' | 'shown-features'): void;
 }
 
+/**
+ * @ignore
+ */
+declare type ConnectionFeatureCollection = FeatureCollection<LineString, ConnectionFeatureProps>;
+
+/**
+ * Properties carried by each connection feature once it is on the map.
+ * @ignore
+ */
+declare type ConnectionFeatureProps = {
+    id: string;
+    fromId?: string;
+    toId?: string;
+    label: string;
+};
+
 /**
  * Allowed CSS cursor styles for map interactions.
  *
@@ -2971,12 +3002,19 @@ export declare type FlowConfig = MapModuleCommonConfig & {
     filters?: TrafficFlowFilters;
 };
 
+/**
+ * Subset of {@link GeoJSONSourceSpecification} fields that {@link GeoJSONSourceWithLayers}
+ * can be configured with at construction time. Forwarded verbatim to MapLibre.
+ * @ignore
+ */
+export declare type GeoJSONSourceClusterOptions = Pick<GeoJSONSourceSpecification, 'cluster' | 'clusterRadius' | 'clusterMaxZoom' | 'clusterMinPoints' | 'clusterProperties'>;
+
 /**
  * @ignore
  */
 export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
     shownFeatures: T;
-    constructor(map: Map_2, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean);
+    constructor(map: Map_2, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean, clusterOptions?: GeoJSONSourceClusterOptions);
     show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
     clear(): void;
     private findFeature;
@@ -3204,6 +3242,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * ```
      */
     moveBeforeLayer(layerConfig: GeometryBeforeLayerConfig): void;
+    private _moveBeforeLayer;
     /**
      * Updates the text/label configuration for displayed geometries.
      *
@@ -4098,6 +4137,7 @@ export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesW
      * ```
      */
     setVisible(visible: boolean): void;
+    private _setVisible;
     /**
      * Checks if the hillshade layer is currently visible.
      *
@@ -4205,6 +4245,24 @@ declare type HillshadeSourcesWithLayers = {
  */
 export declare type HoverEventType = 'hover' | 'hover-move' | 'long-hover';
 
+/**
+ * Visual treatment applied to the focused subset by
+ * {@link TrafficIncidentOverlayModule.setFocus}.
+ *
+ * @group Traffic
+ */
+export declare type IncidentFocusStyle = {
+    /**
+     * Colour of the outline painted beneath the focused stripe. Defaults to `#000`.
+     */
+    outlineColor?: string;
+    /**
+     * Multiplier applied to the line width of focused features. Defaults to `1.6`.
+     * `1` disables the width pop while keeping the outline.
+     */
+    widthScale?: number;
+};
+
 /**
  * Common configuration for traffic incident visualization components.
  *
@@ -4250,6 +4308,12 @@ export declare type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonCon
     icons?: IncidentsCommonConfig;
 };
 
+/**
+ * Dashed-line color for `magnitudeOfDelay === 'indefinite'` (rendered as a gray dashed overlay).
+ * @ignore
+ */
+export declare const INDEFINITE_DELAY_DASH_COLOR = "rgba(137, 150, 168, 1)";
+
 /**
  * @ignore
  */
@@ -4775,6 +4839,11 @@ export declare type MapStylePOICategory = keyof typeof mapDisplayPoiCategoryMapp
  */
 export declare const MIDDLE_INDEX = "middle";
 
+/**
+ * @ignore
+ */
+export declare const MINOR_DELAY_COLOR = "#FFC105";
+
 /**
  * @ignore
  */
@@ -4900,6 +4969,114 @@ export declare type MultiSyntaxFilter = {
     legacy: LegacyFilterSpecification;
 };
 
+/**
+ * Describes a single connection between two places, to be rendered as a line on the map.
+ *
+ * @remarks
+ * Each endpoint can be given either as a full {@link Place} object or as the `id` of a
+ * place that is currently displayed by the {@link PlacesModule} (via `show()`). When an
+ * id is given, the module resolves it against its currently shown places to obtain the
+ * coordinates; connections referencing unknown ids are silently skipped.
+ *
+ * Extra arbitrary properties are preserved on the connection and passed to the optional
+ * label function, making it easy to render metadata such as distance or travel time
+ * along the line.
+ *
+ * @example
+ * ```typescript
+ * const connection: PlaceConnectionDisplay = {
+ *   from: stationPlace,        // full Place object
+ *   to: 'cafe-id-123',         // or a shown place's id
+ *   distanceMeters: 420        // extra metadata available to the label function
+ * };
+ * ```
+ *
+ * @group Places
+ */
+export declare type PlaceConnectionDisplay = {
+    /**
+     * The first endpoint of the connection. Either a Place object or the id of a
+     * place currently shown by the module.
+     */
+    from: Place | string;
+    /**
+     * The second endpoint of the connection. Either a Place object or the id of a
+     * place currently shown by the module.
+     */
+    to: Place | string;
+    /**
+     * Optional stable id for this connection. When omitted, an id is generated.
+     */
+    id?: string;
+    /**
+     * Arbitrary extra metadata, preserved on the connection and passed to the label
+     * function.
+     */
+    [key: string]: unknown;
+};
+
+/**
+ * @group Places
+ */
+export declare type PlaceConnectionLayerName = keyof PlaceConnectionsLayersConfig;
+
+/**
+ * Configuration for rendering connection lines between places.
+ *
+ * @remarks
+ * Controls the appearance of connection lines, the optional label drawn along each
+ * line, and MapLibre layer overrides.
+ *
+ * @example
+ * ```typescript
+ * const config: PlacesModuleConfig = {
+ *   connections: {
+ *     label: (connection) => `${connection.distanceMeters} m`,
+ *     layers: {
+ *       line: { paint: { 'line-color': '#3f9cd9' } }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @group Places
+ */
+export declare type PlaceConnectionsConfig = {
+    /**
+     * Function returning the text to display along the connection line.
+     *
+     * @remarks
+     * Receives the original {@link PlaceConnectionDisplay} (including any custom
+     * metadata). When omitted, no label is rendered.
+     */
+    label?: (connection: PlaceConnectionDisplay) => string;
+    /**
+     * Custom MapLibre layer specifications for connection line and label.
+     */
+    layers?: PlaceConnectionsLayersConfig;
+};
+
+/**
+ * MapLibre layer customization for connection lines and labels.
+ *
+ * @remarks
+ * The layer IDs are derived from the PlacesModule instance prefix plus the key suffix:
+ * - `line`: the connection line (default: dashed)
+ * - `label`: the text label placed along the line
+ *
+ * @group Places
+ */
+export declare type PlaceConnectionsLayersConfig = {
+    /**
+     * Connection line layer specification.
+     */
+    line?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
+    /**
+     * Connection label layer specification.
+     */
+    label?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+};
+
 /**
  * Properties attached to a place feature for rendering on the map.
  *
@@ -5165,95 +5342,69 @@ export declare type PlaceLayersConfig = {
      * This layer reacts to 'hover' and 'click' event states.
      */
     selected?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+    /**
+     * Cluster pin layer specification.
+     *
+     * @remarks
+     * Always registered and stacked above `selected`, but only renders under the
+     * `pin-clustered` theme and only for single-category clusters — every leaf in
+     * the cluster shares the same base-map sprite, picked via a `match` over the
+     * aggregated `clusterBaseMapIconIDs` property. Mixed-category clusters fall
+     * through to {@link clusterMixedBadge} + {@link clusterMixedCount} instead.
+     * For other themes the layer is hidden via `layout.visibility = 'none'`.
+     */
+    cluster?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+    /**
+     * Cluster count badge background layer specification.
+     *
+     * @remarks
+     * Black circle drawn at the top-right of each single-category cluster pin.
+     * Acts as the background for {@link clusterCount}. Only visible under the
+     * `pin-clustered` theme and gated to single-category clusters; mixed
+     * clusters use {@link clusterMixedBadge} instead.
+     */
+    clusterBadge?: Partial<ToBeAddedLayerSpecTemplate<CircleLayerSpecification>>;
+    /**
+     * Cluster count text layer specification.
+     *
+     * @remarks
+     * White count rendered on top of {@link clusterBadge} for single-category
+     * clusters. Reads the `point_count_abbreviated` property MapLibre sets on
+     * every cluster feature. Only visible under the `pin-clustered` theme;
+     * mixed clusters use {@link clusterMixedCount} instead.
+     */
+    clusterCount?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+    /**
+     * Centred count badge for mixed-category clusters under the
+     * `pin-clustered` theme.
+     *
+     * @remarks
+     * Replaces the cluster icon entirely when a cluster spans multiple POI
+     * categories — the count circle takes the centre with
+     * {@link clusterMixedCount} rendered on top. Filter is an "all clusters
+     * with a mixed dedup-concat" check so single-category clusters fall
+     * through to {@link cluster} + {@link clusterBadge} instead.
+     */
+    clusterMixedBadge?: Partial<ToBeAddedLayerSpecTemplate<CircleLayerSpecification>>;
+    /**
+     * Cluster count text on top of {@link clusterMixedBadge}.
+     *
+     * @remarks
+     * Centred count for mixed-category clusters; mirrors
+     * {@link clusterCount} but with no translate so it lands inside the
+     * centred badge.
+     */
+    clusterMixedCount?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
 } & HasAdditionalLayersConfig;
 
-/**
- * Map module for displaying and managing place markers.
- *
- * The PlacesModule provides functionality to display location markers (pins) on the map
- * for points of interest, search results, or custom locations. It supports various marker
- * styles, custom icons, text labels, and interactive events.
- *
- * @remarks
- * **Features:**
- * - Multiple marker styles (pin, circle-icon, base-map POI-like)
- * - Custom icons per POI category
- * - Text labels with styling options
- * - Data-driven styling via MapLibre expressions
- * - Interactive events (click, hover, etc.)
- * - Support for custom feature properties
- * - EV charging station availability display (opt-in)
- *
- * **Marker Styles:**
- * - `pin`: Traditional teardrop-shaped map pins
- * - `circle-icon`: Simple circular markers (previously named `circle`)
- * - `base-map`: Mimics the map's built-in POI layer styling (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
- *
- * **EV Charging Station Availability:**
- * When displaying EV charging stations with availability data from
- * {@link getPlacesWithEVAvailability}, the module can:
- * - Show available/total charging points (e.g., "3/10")
- * - Color-code availability (green = good, orange = limited, red = none/low)
- * - Display as formatted text within the station's label
- *
- * This feature is disabled by default. To enable it, set `evAvailability.enabled` to `true`
- * in the configuration.
- *
- * **Common Use Cases:**
- * - Search result visualization
- * - Custom location markers
- * - Store locators
- * - EV charging station maps with real-time availability
- * - Delivery/pickup points
- * - Saved locations display
- *
- * @example
- * ```typescript
- * // Create places module with pin markers
- * const placesModule = await PlacesModule.get(map, {
- *   icon: {
- *     categoryIcons: []
- *   },
- *   text: {
- *     field: (place) => place.properties.poi?.name || 'Unknown'
- *   },
- *   theme: 'pin'
- * });
- *
- * // Display places from search
- * await placesModule.show(searchResults);
- *
- * // EV Charging Stations - Opt-in to availability display
- * const evStations = await PlacesModule.get(map, {
- *   evAvailability: { enabled: true }
- * });
- * const results = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
- * evStations.show(await getPlacesWithEVAvailability(results)); // Shows availability
- *
- * // Granular control: Enable for searched stations only, background stations without
- * const bgStations = await PlacesModule.get(map); // EV availability disabled
- * const searched = await PlacesModule.get(map, {
- *   evAvailability: { enabled: true }
- * });
- *
- * // Handle clicks
- * placesModule.events.on('click', (feature) => {
- *   console.log('Clicked:', feature.properties);
- * });
- *
- * placesModule.events.on('hover', (feature) => {
- *   showTooltip(feature.properties.poi?.name);
- * });
- * ```
- *
- * @see [Places Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/places)
- *
- * @group Places
- */
 export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
     private static lastInstanceIndex;
     private layerSpecs;
+    private connectionLayerSpecs;
+    private currentClusterMode;
     private sourceID;
+    private unclusteredSourceID;
+    private connectionSourceID;
     private layerIDPrefix;
     /**
      * The index of this instance, to generate unique source and layer IDs.
@@ -5262,6 +5413,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      */
     private instanceIndex;
     private defaultPlaceIconID;
+    private shownConnections;
     private readonly shownFeaturesHandlers;
     /**
      * Make sure the map is ready before create an instance of the module and any other interaction with the map
@@ -5275,7 +5427,10 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * @ignore
      */
     protected _initSourcesWithLayers(config?: PlacesModuleConfig, restore?: boolean): PlacesSourcesAndLayers;
+    private partitionSpecsForSources;
     private buildLayerSpecs;
+    private buildClusterOptions;
+    private buildConnectionLayerSpecs;
     /**
      * @ignore
      */
@@ -5377,6 +5532,9 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
         [key: string]: any;
     }): void;
     private updateLayersAndData;
+    private rebuildSourcesAndLayers;
+    private updateConnectionLayersAndData;
+    private updateConnectionsData;
     private applyPlacesVisibility;
     private setupImages;
     private updateData;
@@ -5441,6 +5599,52 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * ```
      */
     clear(): Promise<void>;
+    /**
+     * Displays connection lines between pairs of places on the map.
+     *
+     * @param connections - List of connections to render. Each connection has a `from`
+     * and `to` endpoint, expressed either as a {@link Place} or as the id of a place
+     * currently shown by this module.
+     *
+     * @remarks
+     * **Behavior:**
+     * - Replaces any previously shown connections
+     * - Connections whose id reference cannot be resolved against the currently shown
+     *   places are silently skipped
+     * - When {@link PlaceConnectionsConfig.label} is set on the module config, the
+     *   returned string is rendered as a label along each line, slightly offset to
+     *   the side. Without a label function, no label is shown.
+     * - Calling `show()` or `clear()` pre-clears connections, since their endpoints
+     *   may no longer be on the map.
+     *
+     * @example
+     * ```typescript
+     * const places = await PlacesModule.get(map, {
+     *   connections: {
+     *     label: (c) => `${c.distanceMeters} m`
+     *   }
+     * });
+     * await places.show([station, ...cafes]);
+     * await places.showConnections(
+     *   cafes.features.map((cafe) => ({
+     *     from: station.id,
+     *     to: cafe.id,
+     *     distanceMeters: Math.round(cafe.properties.dist ?? 0),
+     *   })),
+     * );
+     * ```
+     */
+    showConnections(connections: PlaceConnectionDisplay[]): Promise<void>;
+    /**
+     * Removes all connection lines from the map, leaving displayed places intact.
+     *
+     * @example
+     * ```typescript
+     * await placesModule.clearConnections();
+     * ```
+     */
+    clearConnections(): Promise<void>;
+    private clearConnectionsSync;
     /**
      * Returns the currently shown places.
      *
@@ -5457,6 +5661,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      */
     getShown(): {
         places: Places<DisplayPlaceProps>;
+        connections: PlaceConnectionDisplay[];
     };
     /**
      * Programmatically sets an event state on a specific place.
@@ -5591,6 +5796,15 @@ export declare type PlacesModuleConfig = MapModuleCommonConfig & {
      * @default undefined (disabled)
      */
     evAvailability?: EVAvailabilityConfig;
+    /**
+     * Configuration for connection lines drawn between places via
+     * {@link PlacesModule.showConnections}.
+     *
+     * @remarks
+     * When omitted, connections rendered via `showConnections` use default styling
+     * (a dashed line) and no label.
+     */
+    connections?: PlaceConnectionsConfig;
     /**
      * Additional properties to compute for each place feature.
      *
@@ -5629,9 +5843,24 @@ export declare type PlacesModuleConfig = MapModuleCommonConfig & {
 
 declare type PlacesSourcesAndLayers = {
     /**
-     * Places source id with corresponding layers ids.
+     * Places source id with corresponding layers ids. Carries every layer the
+     * module owns under non-clustered themes; under `pin-clustered` it carries
+     * everything except `micro` and is configured with `cluster: true` so the
+     * pin / cluster pin / cluster-badge / cluster-count / mixed-cluster
+     * badge + count layers all see aggregated cluster features.
      */
     places: GeoJSONSourceWithLayers<Places<DisplayPlaceProps>>;
+    /**
+     * Companion source — only created under `pin-clustered`. Feeds the `micro`
+     * layer with the same place features but **without** clustering, so the
+     * tiny base-map-style POI dots render on every place individually
+     * regardless of how the larger pins above them get aggregated.
+     */
+    placesUnclustered?: GeoJSONSourceWithLayers<Places<DisplayPlaceProps>>;
+    /**
+     * Connections source id with corresponding layers ids (line + label).
+     */
+    connections: GeoJSONSourceWithLayers<ConnectionFeatureCollection>;
 };
 
 /**
@@ -5642,10 +5871,15 @@ declare type PlacesSourcesAndLayers = {
  * - `pin`: Traditional map pin markers (teardrop shape)
  * - `circle-icon`: Simple circular markers (previously named `circle`)
  * - `base-map`: Mimics the map's built-in POI layer style with category icons (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
+ * - `pin-clustered`: Same teardrop pins as `pin` for un-clustered places, with nearby
+ *   places aggregated into a single icon. Single-category clusters render the matching
+ *   base-map POI sprite with a small black count badge in the top-right; mixed-category
+ *   clusters render a larger centred count circle in place of the icon. Cluster features
+ *   expose `clusterBaseMapIconIDs` (comma-separated, deduplicated) on their properties.
  *
  * @group Places
  */
-export declare type PlacesTheme = 'pin' | 'circle-icon' | 'base-map';
+export declare type PlacesTheme = 'pin' | 'circle-icon' | 'base-map' | 'pin-clustered';
 
 /**
  * Configuration for place text labels.
@@ -6102,6 +6336,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
      * ```
      */
     setVisible(visible: boolean): void;
+    private _setVisible;
     /**
      * Filters POIs by category or category group.
      *
@@ -6157,6 +6392,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
      * ```
      */
     filterCategories(categoriesFilter?: ValuesFilter<FilterablePOICategory> | undefined): void;
+    private _filterCategories;
     /**
      * Returns features currently visible in the viewport.
      *
@@ -7611,6 +7847,10 @@ declare type SourceEventTypeHandler = {
     config?: EventHandlerConfig;
 };
 
+declare type Sources = {
+    incidents: GeoJSONSourceWithLayers<TrafficIncidentDetails>;
+};
+
 /**
  * @ignore
  */
@@ -9080,6 +9320,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAn
      * @param layerConfig - Per-layer-type positioning config. Each value is `'top'` or a `MapStyleLayerID`.
      */
     moveBeforeLayer(layerConfig: AreaAnalyticsBeforeLayerConfig): void;
+    private _moveBeforeLayer;
     /**
      * Event interface for the hexgrid and square layers.
      *
@@ -9426,6 +9667,7 @@ export declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSour
      * ```
      */
     setVisible(visible: boolean): void;
+    private _setVisible;
     /**
      * Returns if any layer for traffic flow is visible or not.
      */
@@ -9524,6 +9766,195 @@ declare type TrafficFlowSourcesWithLayers = {
     trafficFlow: StyleSourceWithLayers;
 };
 
+/**
+ * Configuration for {@link TrafficIncidentOverlayModule}.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentOverlayConfig = MapModuleCommonConfig & {
+    /**
+     * Initial visibility of all incident layers. Defaults to `true`.
+     * `show()` never flips this flag — if `false`, the module loads data but
+     * keeps layers hidden until `setVisible(true)` is called.
+     */
+    visible?: boolean;
+    /**
+     * Position incident layers before this map-style layer. Pass `'top'` to
+     * pin them above every other layer. Defaults to `'lowestLabel'`, which
+     * keeps incidents below map labels (roads, places, POIs) so labels stay
+     * readable — the same default the routing, analytics, and geometries
+     * modules use.
+     */
+    beforeLayerConfig?: BeforeLayerConfig;
+    /**
+     * Visual treatment for {@link TrafficIncidentOverlayModule.setFocus}.
+     *
+     * - Omit (or `undefined`) — use the SDK default treatment: a black outline
+     *   beneath the focused stripe and a `1.6×` width pop.
+     * - `false` — disable the visual treatment. `setFocus(ids)` still writes
+     *   MapLibre `feature-state.focused`, so callers can drive their own
+     *   styling (extra layers, sidebar overlays, …) off that state.
+     * - `{ outlineColor?, widthScale? }` — override individual fields of the
+     *   default treatment.
+     */
+    focus?: false | IncidentFocusStyle;
+};
+
+/**
+ * Renders traffic incidents returned by `trafficIncidentDetails()` on the map.
+ *
+ * Use this module when you fetch incidents via the Incident Details service and want
+ * to display them as a developer-controlled overlay. {@link TrafficIncidentsModule} is
+ * the vector-tile alternative — hidden in the default style, so the overlay renders
+ * on its own without collision; if you've enabled it elsewhere in your app, hide it
+ * again before using the overlay to avoid double-rendering.
+ *
+ * ## Rendering approach
+ *
+ * 7–8 layers — 4 to 5 line (optional focus-halo, outline, solid inner, direction chevron,
+ * pattern inner) and 3 symbol (incident marker, jam marker with delay text, closed-road
+ * marker). Per-magnitude styling uses match expressions on `magnitudeOfDelay` inside a
+ * single layer instead of one layer per magnitude. Colours are read from the loaded style
+ * at init (see {@link ./util/readIncidentPalette}), falling back to built-in defaults when
+ * absent. Direction is rendered as a tiled `line-pattern` (chevron sprite registered at
+ * init) instead of the vector-tile module's per-feature `roads-arrow` symbol — the
+ * pattern is continuous, so it reads on short jams and at planning zooms (z12+) where
+ * the per-feature symbol only activates at z15+.
+ *
+ * ## Focus
+ *
+ * {@link setFocus} writes MapLibre feature-state `focused=true|false` on each rendered
+ * incident. The default visual treatment widens the focused subset and paints a black
+ * outline beneath it; unfocused incidents are unchanged. Override or disable the visual
+ * treatment via the `focus` config — `focus: false` keeps `setFocus` writing feature-state
+ * but emits no halo layer and no width pop, leaving callers free to drive their own
+ * styling off `feature-state.focused`.
+ *
+ * ## API limitations
+ *
+ * The Incident Details REST API returns a feature list, not a rendering-ready tile.
+ * Several tags that the vector-tile pipeline injects per-feature are absent:
+ *
+ *  - **Road classification** (`road_category`, `road_subcategory`) — the vector-tile
+ *    pipeline scales line width and offset by road class (motorway wider than street,
+ *    stripe placed alongside the road on one carriageway). Without it, per-road-class
+ *    geometry becomes a guess: we render every incident as a uniform stripe centred on
+ *    the road, no offset.
+ *  - **Traffic-direction side** (`left_hand_traffic`) — only meaningful when paired with
+ *    road-class-driven offset; irrelevant here.
+ *  - **Declutter priority** (`display_class`) — the vector-tile pipeline hides
+ *    low-priority incidents at low zooms; we show everything above the layer minzoom.
+ *  - **Endpoint restriction** (`point_type`) — the vector-tile pipeline limits jam and
+ *    closed-road icons to line endpoints; we render on every matching feature.
+ *  - **Secondary cause** (`icon_category_1`) — the vector-tile pipeline layers a cause
+ *    icon (e.g. accident) over the jam icon; we show only the primary category.
+ *
+ * Callers wanting full per-road-class visual fidelity should use
+ * {@link TrafficIncidentsModule} instead.
+ *
+ * ## Known limitations
+ *
+ * - **Overlapping incidents** — when multiple incidents share the same point or stack
+ *   along the same road segment, MapLibre's symbol collision culling keeps only the
+ *   highest-sort-key feature. Culled features are also invisible to
+ *   `queryRenderedFeatures`, so hover and click cannot reach them. If you need to
+ *   surface multiple incidents at one location, query the source data directly
+ *   (the `FeatureCollection` you passed to {@link show}) rather than relying on
+ *   render-time hit-testing.
+ *
+ * @example
+ * Fetch and render incidents for Amsterdam:
+ * ```typescript
+ * import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
+ * import { TomTomMap, TrafficIncidentOverlayModule } from '@tomtom-org/maps-sdk/map';
+ * import { trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';
+ *
+ * TomTomConfig.instance.put({ apiKey: '<API_KEY>' });
+ *
+ * const map = new TomTomMap({ mapLibre: { container: 'map', center: [4.9, 52.37], zoom: 13 } });
+ *
+ * const overlay = await TrafficIncidentOverlayModule.get(map);
+ * const result = await trafficIncidentDetails({
+ *     bbox: [4.85, 52.34, 4.95, 52.40],
+ *     timeValidityFilter: ['present'],
+ * });
+ * await overlay.show(result);
+ *
+ * // Highlight a subset.
+ * overlay.setFocus([result.features[0].id as string]);
+ * ```
+ *
+ * @see {@link TrafficIncidentsModule} — the vector-tile alternative. Hidden in the
+ *   default style; if you've enabled it explicitly elsewhere in your app, hide it again
+ *   before using the overlay to avoid double-rendering.
+ * @see [Traffic Incident Overlay Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incident-overlay)
+ * @see [Traffic Incident Details Service](https://docs.tomtom.com/maps-sdk-js/guides/services/traffic/traffic-incident-details)
+ *
+ * @group Traffic
+ */
+export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sources, TrafficIncidentOverlayConfig> {
+    private static lastInstanceIndex;
+    private lastResult;
+    private lastFeatureIds;
+    private lastFocusIds;
+    private readonly shownFeaturesHandlers;
+    static get(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayConfig): Promise<TrafficIncidentOverlayModule>;
+    private constructor();
+    /** @ignore */
+    protected _initSourcesWithLayers(config?: TrafficIncidentOverlayConfig): Sources;
+    /** @ignore */
+    protected _applyConfig(config: TrafficIncidentOverlayConfig | undefined): TrafficIncidentOverlayConfig | undefined;
+    private applyBeforeLayer;
+    /** @ignore */
+    protected restoreDataAndConfigImpl(): void;
+    /**
+     * Render the service result. Replaces any previously shown snapshot.
+     */
+    show(result: TrafficIncidentDetails): Promise<void>;
+    /**
+     * Remove all rendered incidents (source kept, data emptied).
+     */
+    clear(): Promise<void>;
+    /**
+     * Show or hide all incident layers.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Whether any incident layer is currently visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Move incident layers before the given map-style layer, or to the top.
+     */
+    moveBeforeLayer(beforeLayerConfig: BeforeLayerConfig): void;
+    /**
+     * Incidents currently rendered in the viewport.
+     */
+    getShown(): {
+        incidents: TrafficIncident[];
+    };
+    /**
+     * Reduce a hit-test result (typically the `features` argument in a click handler) to the
+     * distinct incidents drawn at that point. Each incident renders across multiple layers
+     * (outline + inner + symbol), so `queryRenderedFeatures` returns several entries per
+     * incident — this de-duplicates by feature id.
+     */
+    distinctIncidents(features: readonly MapGeoJSONFeature[]): TrafficIncident[];
+    get events(): CombinedEvents<TrafficIncident, TrafficIncidentOverlayConfig, TrafficIncidentDetails>;
+    /**
+     * Mark a subset of currently-rendered incidents as "focused" via MapLibre
+     * feature-state. `null` clears the state. Paint expressions in
+     * `incidentDetailsLayers.ts` read `['feature-state', 'focused']` and pop the
+     * focused subset (wider stripe + black outline). Unfocused features are
+     * unchanged — the focus treatment adds emphasis, it does not dim the rest.
+     *
+     * No effect if called before `show()`.
+     */
+    setFocus(ids: readonly string[] | null): void;
+    private clearFeatureState;
+    private findSourceFeature;
+}
+
 /**
  * Filter configuration for traffic incidents visualization.
  *
@@ -9723,6 +10154,10 @@ export declare type TrafficIncidentsFilters = {
  *
  * @see [Traffic Incidents Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incidents)
  * @see [Traffic Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic)
+ * @see {@link TrafficIncidentOverlayModule} — for rendering incidents fetched via the
+ *   `trafficIncidentDetails()` REST service as a developer-controlled overlay (use the
+ *   overlay when you need typed incident objects in app code; this vector-tile module
+ *   remains the recommended default for visual fidelity).
  *
  * @group Traffic Incidents
  */
@@ -9880,6 +10315,7 @@ export declare class TrafficIncidentsModule extends AbstractMapModule<TrafficInc
      * ```
      */
     setIconsVisible(visible: boolean): void;
+    private _setIconsVisible;
     /**
      * Sets the visibility of all traffic incident layers.
      *
@@ -10013,11 +10449,22 @@ declare type TrafficIncidentsSourcesWithLayers = {
     trafficIncidents: StyleSourceWithLayers;
 };
 
+/**
+ * @ignore
+ */
+export declare const UNKNOWN_DELAY_BG_COLOR = "#C7D2D8";
+
 /**
  * @ignore
  */
 export declare const UNKNOWN_DELAY_COLOR = "#000000";
 
+/**
+ * Dashed-line color for `magnitudeOfDelay === 'unknown'` (rendered as a red dashed overlay).
+ * @ignore
+ */
+export declare const UNKNOWN_DELAY_DASH_COLOR = "rgba(190, 39, 27, 1)";
+
 /**
  * Handler function for user interaction events on map features.
  *