@tomtom-org/maps-sdk 0.46.13 → 0.47.1

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.
  *
@@ -2286,37 +2317,28 @@ declare type DisplayInstructionArrows = FeatureCollection<Point, Instruction & D
 declare type DisplayInstructions = FeatureCollection<LineString, Instruction & DisplayRouteRelatedProps>;
 
 /**
- * Place base and display properties combined.
- *
- * Merges complete place information from the core API with display-specific
- * properties for rendering on the map.
- *
- * @remarks
- * This is the full type used by the PlacesModule for rendering search results,
- * POIs, and other location markers on the map. It combines:
- * - Geographic data (coordinates, address)
- * - Place metadata (POI info, opening hours, etc.)
- * - Display properties (icon, title, category)
- * - Interactive state (event handling)
+ * Full property shape used by the PlacesModule when rendering a place: the
+ * core place data ({@link CommonPlaceProps}) merged with the display-only
+ * fields the module attaches ({@link PlaceDisplayProps}).
  *
  * @example
  * ```typescript
  * const place: DisplayPlaceProps = {
- *   type: 'Point',
- *   position: { lon: 4.9, lat: 52.3 },
+ *   type: 'POI',
+ *   poi: {
+ *     name: 'Central Station',
+ *     categories: ['RAILWAY_STATION'],
+ *   },
  *   address: {
  *     streetName: 'Damrak',
  *     municipalitySubdivision: 'Amsterdam',
- *     countryCode: 'NL'
- *   },
- *   poi: {
- *     name: 'Central Station',
- *     categories: ['RAILWAY_STATION']
+ *     countryCode: 'NL',
  *   },
  *   id: 'place-123',
  *   title: 'Amsterdam Central Station',
- *   iconID: 'poi-transit',
- *   category: 'RAILWAY_STATION'
+ *   iconID: 'poi-railway_station',
+ *   category: 'railway_station',
+ *   group: 'transport',
  * };
  * ```
  *
@@ -2980,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;
@@ -3213,6 +3242,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * ```
      */
     moveBeforeLayer(layerConfig: GeometryBeforeLayerConfig): void;
+    private _moveBeforeLayer;
     /**
      * Updates the text/label configuration for displayed geometries.
      *
@@ -3920,11 +3950,18 @@ export declare const getLineForegroundWidth: (size?: RouteWidth) => ExpressionSp
  */
 export declare const getLineOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
 
+/**
+ * Maps a Place to the base map POI group used by the style's `text-color` and
+ * `POI - Micro` icon expressions (e.g., `eat_and_drink`, `lodging`, `driving`).
+ * @ignore
+ */
+export declare const getPOIGroupForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
+
 /**
  * Maps a Place category to the poi layer one, so the latter's style can apply it.
  * @ignore
  */
-export declare const getPOILayerCategoryForPlace: (place: Place) => string | undefined;
+export declare const getPOILayerCategoryForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
 
 /**
  * Gets the specified filtered categories icon IDs to be used in map filtering.
@@ -4100,6 +4137,7 @@ export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesW
      * ```
      */
     setVisible(visible: boolean): void;
+    private _setVisible;
     /**
      * Checks if the hillshade layer is currently visible.
      *
@@ -4207,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.
  *
@@ -4252,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
  */
@@ -4777,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
  */
@@ -4903,29 +4970,146 @@ export declare type MultiSyntaxFilter = {
 };
 
 /**
- * Properties to display a place on the map.
+ * 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' } }
+ *     }
+ *   }
+ * };
+ * ```
  *
- * Extends basic place information with display-specific properties needed
- * for rendering markers, icons, and labels on the map.
+ * @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
- * **Use Cases:**
- * - Search result markers
- * - POI markers
- * - Custom location pins
- * - EV charging station markers
+ * 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.
  *
- * These properties control how the place appears visually on the map,
- * including its icon, label, and interactive states.
+ * @remarks
+ * Extends the source place with display-only fields consumed by the places
+ * layer stack. Which fields are populated depends on the active
+ * {@link PlacesTheme | theme}:
+ *
+ * - Every theme uses {@link PlaceDisplayProps.iconID | iconID} — the sprite name
+ *   the main layer's `icon-image` expression binds to via `['get', 'iconID']`.
+ *   The base map's POI-Micro-like layer inherits the style's `['get','group']`
+ *   expression verbatim, so custom `PlaceIconConfig.categoryIcons` sprites only
+ *   apply to the `main` layer.
+ * - The `base-map` theme additionally populates
+ *   {@link PlaceDisplayProps.category | category} and
+ *   {@link PlaceDisplayProps.group | group} so the base map style's own
+ *   `text-color` expression — and the POI-Micro layer's `icon-image` expression
+ *   — resolve against the place feature just as they do for native POIs.
  *
  * @example
  * ```typescript
- * const locationProps: LocationDisplayProps = {
+ * const pinPlaceProps: PlaceDisplayProps = {
  *   id: 'place-123',
  *   title: 'Central Station',
  *   iconID: 'poi-transit',
- *   category: 'RAILWAY_STATION',
- *   eventState: 'hover'
+ * };
+ *
+ * const baseMapPlaceProps: PlaceDisplayProps = {
+ *   id: 'place-123',
+ *   title: 'Central Station',
+ *   iconID: 'poi-railway_station',
+ *   category: 'railway_station',
+ *   group: 'transport',
  * };
  * ```
  *
@@ -4936,87 +5120,81 @@ export declare type PlaceDisplayProps = {
      * Unique identifier for the place feature.
      *
      * @remarks
-     * MapLibre does not reuse the feature IDs. Either we generate it on the fly
-     * or use the one from properties via promotedId value.
-     *
-     * Used for:
-     * - Feature identification in events
-     * - State management
-     * - Data updates
+     * MapLibre does not reuse the feature IDs, so we either generate one on the
+     * fly or promote the one from `properties.id` via the source's `promoteId`
+     * option. Used for feature identification in events, hit-testing, and data
+     * updates.
      *
      * @example
      * ```typescript
      * id: 'place-123'
-     * id: 'poi-456'
      * ```
      */
     id: string;
     /**
-     * Display title for the place on the map.
+     * Text label rendered next to the place marker.
      *
      * @remarks
-     * Optional text label shown near the place marker. If not provided,
-     * no text label will be displayed.
-     *
-     * **Common Sources:**
-     * - POI name (e.g., "Starbucks")
-     * - Address (e.g., "123 Main Street")
-     * - Custom label (e.g., "Meeting Point")
+     * Optional — when absent no label is drawn. Typically sourced from the POI
+     * name or free-form address, but can be any custom string (e.g., configured
+     * via `PlacesModuleConfig.text.title`).
      *
      * @example
      * ```typescript
      * title: 'Amsterdam Central Station'
-     * title: 'Starbucks'
-     * title: '123 Main Street'
-     * title: undefined  // No label
      * ```
      */
     title?: string;
     /**
-     * Icon ID referencing the map style sprite.
+     * Sprite image ID used to draw the place marker.
      *
      * @remarks
-     * References an icon image in the map's sprite sheet. The icon must exist
-     * in the map style or be added programmatically.
-     *
-     * **Icon Types:**
-     * - Built-in POI icons (e.g., 'poi-restaurant', 'poi-hotel')
-     * - Custom icons added to the sprite
-     * - Pin/marker icons (e.g., 'pin-red', 'pin-blue')
+     * The main layer binds `icon-image` to `['get', 'iconID']`, so the sprite
+     * named here is what renders. The base map's POI-Micro-like layer inherits
+     * the style's group-driven expression verbatim and ignores this value. The
+     * sprite name is resolved per theme: `pin` / `circle-icon` pick a built-in
+     * sprite; `base-map` picks the base map's `poi-<category>` sprite; a custom
+     * `PlaceIconConfig.categoryIcons` entry overrides the default for the main
+     * layer on any theme.
      *
      * @example
      * ```typescript
-     * iconID: 'poi-restaurant'
-     * iconID: 'pin-red'
-     * iconID: 'custom-marker'
+     * iconID: '7315'              // pin theme sprite
+     * iconID: 'poi-restaurant'    // circle-icon / base-map theme sprite
+     * iconID: 'custom-marker-0'   // user-provided custom icon
      * ```
      */
     iconID: string;
     /**
-     * Map-style-compatible display category, mostly applicable for base-map places.
+     * Base map style POI category the place should be rendered as.
      *
      * @remarks
-     * Used to match the place with a POI category in the map style, enabling
-     * category-specific styling and filtering.
-     *
-     * **Common Categories:**
-     * - RESTAURANT
-     * - HOTEL_MOTEL
-     * - GAS_STATION
-     * - PARKING_GARAGE
-     * - SHOPPING
-     *
-     * Optional - only needed when using base-map styling or category-based filtering.
+     * Populated only for the `base-map` theme. Values are the lowercased
+     * identifiers used by the base map style (derived via
+     * {@link toBaseMapPOICategory}). Drives the inherited `text-color`
+     * expression on the main/selected POI-like layers.
      *
      * @example
      * ```typescript
-     * category: 'RESTAURANT'
-     * category: 'HOTEL_MOTEL'
-     * category: 'EV_CHARGING_STATION'
-     * category: undefined  // No category association
+     * category: 'restaurant'
+     * category: 'hotel_or_motel'
+     * category: 'charging_location'
      * ```
      */
     category?: string;
+    /**
+     * Base map style POI group the place belongs to.
+     *
+     * @remarks
+     * Populated only for the `base-map` theme. Drives the inherited
+     * `text-color` expression on the base map's POI layers.
+     * Valid values are those produced by {@link toBaseMapPOIGroup} — e.g.,
+     * `eat_and_drink`, `lodging`, `driving`, `transport`, `shopping`,
+     * `healthcare`, `finance`, `cultural`, `leisure`, `sport`, `outdoor`,
+     * `protected`, `public`, `religion`, `military`, `business`, `education`,
+     * `parking`.
+     */
+    group?: string;
 } & SupportsEvents & Anything;
 
 /**
@@ -5141,6 +5319,18 @@ export declare type PlaceLayersConfig = {
      * This layer renders places that are not in a highlighted/selected state.
      */
     main?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+    /**
+     * Micro place marker layer specification.
+     *
+     * @remarks
+     * Always registered and stacked below the `main` layer, but only renders features
+     * when the `base-map` theme is active — in that mode it mirrors the map style's
+     * `POI - Micro` layer so place markers blend with the base map's lower-density
+     * POI rendering. For other themes the layer is hidden via
+     * `layout.visibility = 'none'` and acts as a no-op, making theme switches cheap
+     * (no add/remove layer churn).
+     */
+    micro?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
     /**
      * Selected place marker layer specification.
      *
@@ -5152,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, 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`: Simple circular markers
- * - `base-map`: Mimics built-in POI layer styling
- *
- * **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.
@@ -5249,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
@@ -5262,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
      */
@@ -5279,8 +5447,8 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * @remarks
      * **Available Themes:**
      * - `pin`: Traditional teardrop-shaped map pins
-     * - `circle`: Simple circular markers
-     * - `base-map`: Mimics the map's built-in POI layer style with category icons
+     * - `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`). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
      *
      * Changes apply immediately to all currently shown places. Other configuration
      * properties (icon config, text config) remain unchanged.
@@ -5291,7 +5459,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * placesModule.applyTheme('pin');
      *
      * // Use simple circles
-     * placesModule.applyTheme('circle');
+     * placesModule.applyTheme('circle-icon');
      *
      * // Match map's POI style (ideal to blend in)
      * placesModule.applyTheme('base-map');
@@ -5364,6 +5532,10 @@ 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;
     /**
@@ -5427,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.
      *
@@ -5443,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.
@@ -5577,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.
      *
@@ -5615,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>;
 };
 
 /**
@@ -5626,12 +5869,17 @@ declare type PlacesSourcesAndLayers = {
  * @remarks
  * **Available Styles:**
  * - `pin`: Traditional map pin markers (teardrop shape)
- * - `circle`: Simple circular markers
- * - `base-map`: Mimics the map's built-in POI layer style with category icons
+ * - `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' | 'base-map';
+export declare type PlacesTheme = 'pin' | 'circle-icon' | 'base-map' | 'pin-clustered';
 
 /**
  * Configuration for place text labels.
@@ -6088,6 +6336,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
      * ```
      */
     setVisible(visible: boolean): void;
+    private _setVisible;
     /**
      * Filters POIs by category or category group.
      *
@@ -6143,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.
      *
@@ -7597,6 +7847,10 @@ declare type SourceEventTypeHandler = {
     config?: EventHandlerConfig;
 };
 
+declare type Sources = {
+    incidents: GeoJSONSourceWithLayers<TrafficIncidentDetails>;
+};
+
 /**
  * @ignore
  */
@@ -8080,6 +8334,11 @@ export declare const themedGeometryConfig: (palette?: ColorPaletteOptions, befor
  */
 export declare const toBaseMapPOICategory: (category: POICategory) => string;
 
+/**
+ * @ignore
+ */
+export declare const toBaseMapPOIGroup: (category: POICategory) => string | undefined;
+
 /**
  * Layer to be added to the existing style, and may include extra config such as the ID of the layer to add it under.
  * * e.g. GeoJSON layers.
@@ -9061,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.
      *
@@ -9407,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.
      */
@@ -9505,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.
  *
@@ -9704,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
  */
@@ -9861,6 +10315,7 @@ export declare class TrafficIncidentsModule extends AbstractMapModule<TrafficInc
      * ```
      */
     setIconsVisible(visible: boolean): void;
+    private _setIconsVisible;
     /**
      * Sets the visibility of all traffic incident layers.
      *
@@ -9994,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.
  *