@tomtom-org/maps-sdk 0.47.9 → 0.48.1

package/map/dist/index.d.ts

@@ -111,6 +111,18 @@ declare abstract class AbstractEventProxy {
      * @param sourceId The source id (should be linked to a SourceWithLayers instance).
      */
     hasSourceID(sourceId: string): boolean;
+    /**
+     * Look up the {@link SourceWithLayers} registered for the given source ID, if any.
+     *
+     * The SDK assumes at most one `SourceWithLayers` per MapLibre source ID — each
+     * module creates its own source — so any non-empty handler bucket gives us the
+     * right reference. We iterate event-type buckets defensively to skip transient
+     * empty arrays left mid-`removeHandler` before the bucket itself is deleted.
+     *
+     * NOTE: if two modules ever register against the same source ID with overlapping
+     * layers, this returns the first one we encounter.
+     */
+    protected sourceWithLayersFor(sourceId: string | undefined): SourceWithLayers | undefined;
     /**
      * Updates the given sourcesWithLayers, if they have any handlers.
      * * (This is typically called to refresh any registered, stale sourceWithLayers references after a map style has changed).
@@ -3148,6 +3160,18 @@ export declare class EventsProxy extends AbstractEventProxy {
     enable(enabled: boolean): void;
     private toPaddedBounds;
     private isEnabled;
+    /**
+     * Build the consumer-facing `allEventFeatures`: scope to the firing source, dedupe, then
+     * substitute cached typed originals. Scope and dedupe run on the raw features, since
+     * `.source` and the rendered id survive only before substitution; the top hit stays first.
+     *
+     * Scoping leaves only `firingSource`'s hits, so its {@link SourceWithLayers} is resolved once
+     * here rather than per feature. For GeoJSON-backed sources we substitute the cached typed
+     * original (un-stringified properties, real Dates, nested objects); for everything else — vector
+     * tiles, unregistered sources — the MapLibre-rendered feature passes through (`MapGeoJSONFeature
+     * extends Feature`).
+     */
+    private toCallerFeatures;
     private getRenderedFeatures;
     private clearLongHoverTimeout;
     private restartLongHoverTimeout;
@@ -3321,6 +3345,13 @@ export declare type FilterShowMode = 'all_except' | 'only';
  */
 export declare type FilterSyntaxVersion = 'expression' | 'legacy';
 
+/**
+ * Find the first feature whose {@link renderedRefId} equals `id`, with its index, or
+ * `undefined` (also for a nullish `id`).
+ * @ignore
+ */
+export declare const findFeatureByRefId: <F extends RenderedRef>(features: readonly F[], id: string | number | undefined) => IndexedFeature<F> | undefined;
+
 /**
  * @group Routing
  */
@@ -3366,6 +3397,11 @@ export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = Featu
     shownFeatures: T;
     constructor(map: Map_2, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean, clusterOptions?: GeoJSONSourceClusterOptions);
     show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
+    /**
+     * Canonical id-based lookup into `shownFeatures.features` via {@link findFeatureByRefId}
+     * (first match wins on duplicate ids). Returns `undefined` for a nullish or absent id.
+     */
+    findById(id: string | number | undefined): IndexedFeature<T['features'][number]> | undefined;
     clear(): void;
     private findFeature;
     putEventState(options: PutEventStateOptions): void;
@@ -4668,6 +4704,12 @@ export declare const INDEFINITE_DELAY_DASH_COLOR = "rgba(137, 150, 168, 1)";
  */
 export declare const INDEX_TYPE = "indexType";
 
+/** A feature together with its index in the array it was found in. @ignore */
+export declare type IndexedFeature<F> = {
+    feature: F;
+    index: number;
+};
+
 /**
  * Complete TomTom map parameters after merging with global configuration.
  * This type represents the fully resolved configuration used internally by the SDK.
@@ -7103,6 +7145,33 @@ export declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOption
 /** Custom label generator for reachable range features. */
 export declare type ReachableRangeLabelFn = (feature: PolygonFeature, index: number) => string;
 
+/**
+ * Class-independent feature-id recovery and lookup, shared by the event subsystem and the
+ * source/layer caches. Operate on the minimal {@link RenderedRef} shape, so they accept
+ * MapLibre `MapGeoJSONFeature`s, plain GeoJSON `Feature`s, and cached originals alike.
+ */
+/** Minimal shape needed to look a feature up by id. @ignore */
+export declare type RenderedRef = {
+    id?: string | number;
+    properties?: {
+        id?: unknown;
+    } | null;
+};
+
+/**
+ * Recover the SDK-assigned id of a feature, preferring `properties.id` over the top-level `id`.
+ *
+ * The SDK always stamps the real id into `properties.id` and uses `promoteId: 'id'`, so MapLibre
+ * mirrors it onto the top-level `id` — the two are normally identical. The exception is **clustered**
+ * GeoJSON sources: clustering disables `promoteId`, and MapLibre's supercluster then assigns its own
+ * **synthetic** numeric top-level `id` (0, 1, 2, …) to rendered features. Preferring the top-level
+ * `id` there would return that synthetic value and miss the cache, whereas `properties.id` is still
+ * the real id. So read `properties.id` first, falling back to the top-level `id` (e.g. vector-tile
+ * features that only carry a top-level id). Returns `undefined` when neither is set.
+ * @ignore
+ */
+export declare const renderedRefId: (rendered: RenderedRef) => string | number | undefined;
+
 /**
  * Resolves the effective color stops for a given color configuration.
  * @ignore
@@ -10215,7 +10284,7 @@ export declare type TrafficIncidentOverlayConfig = MapModuleCommonConfig & {
  * await overlay.show(result);
  *
  * // Highlight a subset.
- * overlay.setFocus([result.features[0].id as string]);
+ * overlay.setFocus([result.features[0].properties.id as string]);
  * ```
  *
  * @see {@link TrafficIncidentsModule} — the vector-tile alternative. Hidden in the
@@ -10261,18 +10330,17 @@ export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sour
      */
     moveBeforeLayer(beforeLayerConfig: BeforeLayerConfig): void;
     /**
-     * Incidents currently rendered in the viewport.
+     * Returns the currently shown incidents — the exact data that was passed to {@link show}.
+     *
+     * Reads the module's client-side cache (`shownFeatures`), mirroring the other GeoJSON
+     * modules (`PlacesModule`, `TrafficAreaAnalyticsModule`, `GeometriesModule`). It does
+     * **not** hit-test the viewport: the proxy already scopes and de-duplicates the
+     * `allEventFeatures` it dispatches to click handlers, so no caller needs viewport-level
+     * de-duplication here.
      */
     getShown(): {
-        incidents: TrafficIncident[];
+        incidents: TrafficIncidentDetails;
     };
-    /**
-     * 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
@@ -10285,7 +10353,6 @@ export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sour
      */
     setFocus(ids: readonly string[] | null): void;
     private clearFeatureState;
-    private findSourceFeature;
 }
 
 /**
@@ -10818,7 +10885,7 @@ export declare const UNKNOWN_DELAY_DASH_COLOR = "rgba(190, 39, 27, 1)";
  *
  * @param topFeature - The primary target feature for the event, positioned on top of any overlapping features
  * @param lngLat - The geographic coordinates where the event occurred
- * @param allEventFeatures - All features matching the event coordinates across all map modules, as raw MapLibre GeoJSON features. The first feature corresponds to `topFeature`
+ * @param allEventFeatures - The features at the event coordinates, scoped to the module whose handler fired and de-duplicated (a feature drawn across multiple layers or tiles appears once). Entries from GeoJSON-backed modules (places, routes, geometries) are the original typed `Feature` you passed to `show()`, with un-stringified properties (nested objects, Dates, arrays); entries from vector-tile modules (POIs, traffic) are the underlying `MapGeoJSONFeature` (which extends `Feature`). The first entry is the same feature as `topFeature` — though for modules with a mapping callback, `topFeature` is the mapped shape while this entry stays raw. To inspect **every** feature at the point across all modules — including the base map, with `.source`/`.layer` intact — query MapLibre directly (note `lngLat` is geographic, so project it to a pixel first): `const p = map.mapLibreMap.project(lngLat); const all = map.mapLibreMap.queryRenderedFeatures([[p.x - 5, p.y + 5], [p.x + 5, p.y - 5]]);`
  * @param sourceWithLayers - The source and layer configuration to which the `topFeature` belongs
  *
  * @example
@@ -10853,7 +10920,7 @@ export declare const UNKNOWN_DELAY_DASH_COLOR = "rgba(190, 39, 27, 1)";
  *
  * @group User Interaction Events
  */
-export declare type UserEventHandler<T> = (topFeature: T, lngLat: LngLat, allEventFeatures: MapGeoJSONFeature[], sourceWithLayers: SourceWithLayers) => void;
+export declare type UserEventHandler<T> = (topFeature: T, lngLat: LngLat, allEventFeatures: T[], sourceWithLayers: SourceWithLayers) => void;
 
 /**
  * Event handling interface for map features.
@@ -10989,14 +11056,20 @@ export declare class UserEvents<T = MapGeoJSONFeature> {
      * @param type The type of event to listen for (click, contextmenu, hover, long-hover)
      * @param handler Callback function invoked when the event occurs
      *
+     * @returns An unsubscribe function that removes the handler registered by this call.
+     *
      * @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)
+     * - `features`: The features from this module at the event location, de-duplicated (for
+     *   overlapping features within the module). To inspect features across all modules, query
+     *   `map.mapLibreMap.queryRenderedFeatures(...)` directly — see {@link UserEventHandler}.
      *
      * **Behavior:**
-     * - Only one handler per event type (calling `on()` again replaces the previous handler)
+     * - Multiple handlers per event type are supported — each `on()` adds a handler (it does
+     *   **not** replace existing ones) and all of them fire. To remove one, call the unsubscribe
+     *   this returns; to clear them all, use `off(type)`.
      * - Handlers are preserved across map style changes
      * - Cursor automatically changes to pointer on hover
      * - Events respect module visibility (hidden features don't trigger events)
@@ -11064,7 +11137,9 @@ export declare class UserEvents<T = MapGeoJSONFeature> {
      *
      * @remarks
      * **Cleanup Behavior:**
-     * - Removes only the specified event type (other types remain active)
+     * - Removes **all** handlers for the specified event type — to remove a single handler, call
+     *   the unsubscribe function returned by {@link on}
+     * - Other event 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