@tomtom-org/maps-sdk 0.45.7 → 0.45.9

package/core/dist/index.d.ts

@@ -2597,6 +2597,17 @@ export declare type HasCount = {
  */
 export declare type HasLngLat = [number, number] | Position | Point | Feature<Point>;
 
+/**
+ * Maps an `iconCategory` integer from the Incident Details API to a {@link TrafficIncidentCategory}.
+ * Integer values that do not correspond to a known category are mapped to `'other'`.
+ *
+ * @param iconCategory - Integer category code from the API response
+ * @returns The corresponding {@link TrafficIncidentCategory}
+ *
+ * @ignore
+ */
+export declare const iconToTrafficIncidentCategory: (iconCategory: number) => TrafficIncidentCategory;
+
 /**
  * Sections with important stretches of road information.
  *
@@ -4764,6 +4775,63 @@ export declare const toPointFeature: (coordinates: Position) => Feature<Point>;
  */
 export declare const toPointGeometry: (coordinates: Position) => Point;
 
+/**
+ * A GeoJSON Feature representing a single traffic incident.
+ *
+ * The geometry is a `Point` for localised incidents or a `LineString`
+ * for incidents that span a stretch of road.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncident = Feature<Point | LineString, TrafficIncidentProperties>;
+
+/**
+ * Properties common to all traffic incident representations.
+ *
+ * @remarks
+ * Shared between the Incident Details service response and map vector-tile features.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentBaseProperties = {
+    /**
+     * Unique identifier of the incident.
+     */
+    id: string;
+    /**
+     * Primary category of the incident.
+     */
+    category: TrafficIncidentCategory;
+    /**
+     * Severity of the delay caused by this incident.
+     */
+    magnitudeOfDelay: DelayMagnitude;
+    /**
+     * Estimated delay caused by the incident in seconds.
+     */
+    delayInSeconds?: number;
+    /**
+     * Time when the incident started or is expected to start.
+     */
+    startTime?: Date;
+    /**
+     * Time when the incident ended or is expected to end.
+     */
+    endTime?: Date;
+    /**
+     * Confidence in the occurrence of the incident.
+     */
+    probabilityOfOccurrence?: TrafficIncidentProbability;
+    /**
+     * Number of user reports that contributed to this incident.
+     */
+    numberOfReports?: number;
+    /**
+     * Time of the most recent user report for this incident.
+     */
+    lastReportTime?: Date;
+};
+
 /**
  * All possible traffic incident categories.
  * @group Traffic
@@ -4794,6 +4862,90 @@ export declare const trafficIncidentCategories: readonly ["accident", "animals-o
  */
 export declare type TrafficIncidentCategory = (typeof trafficIncidentCategories)[number];
 
+/**
+ * Response from the Incident Details service.
+ *
+ * Extends the GeoJSON `FeatureCollection` standard, where each feature
+ * is a {@link TrafficIncident}.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentDetails = FeatureCollection<Point | LineString, TrafficIncidentProperties>;
+
+/**
+ * A single event contributing to a traffic incident.
+ *
+ * Incidents may have one or more events describing different aspects of the situation.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentEvent = {
+    /**
+     * Human-readable description of the event.
+     */
+    description: string;
+    /**
+     * Numeric event code.
+     */
+    code: number;
+    /**
+     * Category of this specific event.
+     */
+    category: TrafficIncidentCategory;
+};
+
+/**
+ * Likelihood that an incident will actually occur.
+ *
+ * @remarks
+ * - `certain`: The incident is confirmed and currently active
+ * - `probable`: The incident is very likely to be occurring
+ * - `risk_of`: There is a risk of this incident occurring
+ * - `improbable`: The incident is unlikely to be occurring
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentProbability = 'certain' | 'probable' | 'risk_of' | 'improbable';
+
+/**
+ * Full properties of a traffic incident from the Incident Details service.
+ *
+ * Extends {@link TrafficIncidentBaseProperties} with fields available in the
+ * Incident Details API response but not in map vector-tile features.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentProperties = TrafficIncidentBaseProperties & {
+    /**
+     * One or more events describing the incident in detail.
+     */
+    events: TrafficIncidentEvent[];
+    /**
+     * Human-readable description of the start of the affected road.
+     */
+    from?: string;
+    /**
+     * Human-readable description of the end of the affected road.
+     */
+    to?: string;
+    /**
+     * Length of the affected road section in meters.
+     */
+    lengthInMeters?: number;
+    /**
+     * Road numbers (e.g. highway designations) affected by the incident.
+     */
+    roadNumbers?: string[];
+    /**
+     * Whether the incident is currently active or expected in the future.
+     */
+    timeValidity: TrafficIncidentTimeValidity;
+    /**
+     * TMC data for the incident, if available.
+     */
+    tmc?: TrafficIncidentTMC;
+};
+
 /**
  * Traffic incident information based on TPEG2-TEC standard.
  *
@@ -4817,6 +4969,75 @@ export declare type TrafficIncidentTEC = {
     causes?: [CauseTEC, ...CauseTEC[]];
 };
 
+/**
+ * Whether a traffic incident is currently active or anticipated in the future.
+ *
+ * @remarks
+ * - `present`: The incident is currently active
+ * - `future`: The incident is scheduled or predicted to occur in the future
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentTimeValidity = 'present' | 'future';
+
+/**
+ * Traffic Message Channel (TMC) data associated with a traffic incident.
+ *
+ * TMC is an international standard for encoding traffic and travel information
+ * in FM radio broadcasts (RDS-TMC) and digital data streams.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentTMC = {
+    /**
+     * ISO 3166-1 alpha-2 country code.
+     */
+    countryCode: string;
+    /**
+     * TMC table number.
+     */
+    tableNumber: string;
+    /**
+     * TMC table version.
+     */
+    tableVersion: string;
+    /**
+     * Direction of the incident along the TMC path.
+     */
+    direction: 'positive' | 'negative';
+    /**
+     * Ordered list of TMC location points describing the incident extent.
+     */
+    points: TrafficIncidentTMCPoint[];
+};
+
+/**
+ * A single TMC (Traffic Message Channel) location point.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentTMCPoint = {
+    /**
+     * TMC location code.
+     */
+    location: number;
+    /**
+     * Offset from the TMC location in the direction of the incident.
+     */
+    offset?: number;
+};
+
+/**
+ * Maps a {@link TrafficIncidentCategory} string to the `iconCategory` integer used by the API.
+ * `'other'` and any unrecognised values map to `0`.
+ *
+ * @param category - The string category
+ * @returns The corresponding integer icon category code
+ *
+ * @ignore
+ */
+export declare const trafficIncidentToIconCategory: (category: TrafficIncidentCategory) => number;
+
 /**
  * Route section affected by a traffic incident.
  *

package/map/dist/index.d.ts

@@ -48,7 +48,9 @@ import { Source } from 'maplibre-gl';
 import { SourceSpecification } from 'maplibre-gl';
 import { StyleSpecification } from 'maplibre-gl';
 import { SymbolLayerSpecification } from 'maplibre-gl';
+import { TrafficIncidentBaseProperties } from '@tomtom-org/maps-sdk/core';
 import { TrafficIncidentCategory } 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';
 import { WaypointLike } from '@tomtom-org/maps-sdk/core';
@@ -3503,6 +3505,28 @@ export declare type GeometryLineLabelConfig = {
      * ```
      */
     symbolSpacing?: number;
+    /**
+     * Opacity of the border label text.
+     *
+     * @default 1
+     *
+     * @example
+     * ```typescript
+     * textOpacity: 0.8
+     * ```
+     */
+    textOpacity?: DataDrivenPropertyValueSpecification<number>;
+    /**
+     * Offset of the border label from the line, in ems `[x, y]`.
+     *
+     * @default [0, 1]
+     *
+     * @example
+     * ```typescript
+     * textOffset: [0, 1]  // Default: 1em above the line
+     * ```
+     */
+    textOffset?: DataDrivenPropertyValueSpecification<[number, number]>;
 };
 
 /**
@@ -5965,13 +5989,6 @@ export declare const preparePlacesForDisplay: (placesInput: Place | Place[] | Pl
  */
 export declare const prepareReachableRangesForDisplay: (result: PolygonFeatures, theme?: GeometryTheme, label?: ReachableRangeLabelFn) => PolygonFeatures;
 
-/**
- * Likelihood of a traffic incident occurring.
- *
- * @group Traffic
- */
-export declare type ProbabilityOfOccurrence = 'certain' | 'probable' | 'risk_of' | 'improbable';
-
 /**
  * Parameters to update the event state of a feature programmatically.
  *
@@ -6059,6 +6076,7 @@ export declare type PutEventStateOptions = ByIdOrIndex & {
  *
  * @param palette Color palette. Defaults to `'fadedRainbow'`.
  * @param theme Visual theme. Defaults to `'filled'`.
+ * @param beforeLayerConfig Layer positioning. Defaults to `'lowestLabel'`.
  * @param label Custom label generator; when omitted, labels are derived from `budget` property.
  *
  * @example
@@ -6070,7 +6088,7 @@ export declare type PutEventStateOptions = ByIdOrIndex & {
  *
  * @group Geometries
  */
-export declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOptions, theme?: GeometryTheme, label?: ReachableRangeLabelFn) => GeometriesModuleConfig;
+export declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOptions, theme?: GeometryTheme, beforeLayerConfig?: GeometryBeforeLayerConfig, label?: ReachableRangeLabelFn) => GeometriesModuleConfig;
 
 /** Custom label generator for reachable range features. */
 export declare type ReachableRangeLabelFn = (feature: PolygonFeature, index: number) => string;
@@ -7520,17 +7538,11 @@ export declare type SymbolLayerSpecWithoutSource = Omit<SymbolLayerSpecification
  * with auto-generated labels.
  *
  * @param palette Color palette for polygon fills. Defaults to `'fadedRainbow'`.
+ * @param beforeLayerConfig Layer positioning. Defaults to `'lowestLabel'`.
  *
  * @group Geometries
  */
-export declare const themedGeometryConfig: (palette?: ColorPaletteOptions) => GeometriesModuleConfig;
-
-/**
- * Whether the incident is currently active or expected in the future.
- *
- * @group Traffic
- */
-export declare type TimeValidity = 'present' | 'future';
+export declare const themedGeometryConfig: (palette?: ColorPaletteOptions, beforeLayerConfig?: GeometryBeforeLayerConfig) => GeometriesModuleConfig;
 
 /**
  * @ignore
@@ -9102,27 +9114,11 @@ export declare type TrafficIncidentsModuleFeature = Omit<MapGeoJSONFeature, 'pro
      * @remarks
      * These properties include a unique identifier for the incident, a description of the incident, its category, the magnitude of any resulting delay, and information about the road where the incident is occurring (including road category and subcategory). Additionally, it indicates whether the incident is in a left-hand traffic region.
      */
-    properties: {
-        /**
-         * Unique identifier for the traffic incident, common across Traffic API services.
-         */
-        id: string;
+    properties: TrafficIncidentBaseProperties & {
         /**
          * Description of the traffic incident, providing details about the nature of the incident.
          */
         description: string;
-        /**
-         * Category of the traffic incident, classifying the type of incident (e.g., accident, roadworks, congestion) based on predefined categories.
-         */
-        category: TrafficIncidentCategory;
-        /**
-         * Severity of the delay.
-         */
-        magnitudeOfDelay: DelayMagnitude;
-        /**
-         * The delay caused by the incident in seconds (except in road closures). It is calculated against free-flow travel time (the travel time when the traffic is minimal, e.g., night traffic).
-         */
-        delayInSeconds?: number;
         /**
          * Road hierarchy category type.
          */
@@ -9139,26 +9135,6 @@ export declare type TrafficIncidentsModuleFeature = Omit<MapGeoJSONFeature, 'pro
          * Indicates whether the incident covers different directional geometries (i.e. both directions of a two-way road).
          */
         partOfTwoWayRoad?: boolean;
-        /**
-         * The date and time when the incident started.
-         */
-        startTime?: Date;
-        /**
-         * The estimated date and time when the incident will end.
-         */
-        endTime?: Date;
-        /**
-         * Likelihood assessment of the incident occurring.
-         */
-        probabilityOfOccurrence?: ProbabilityOfOccurrence;
-        /**
-         * Number of user reports for the incident.
-         */
-        numberOfReports?: number;
-        /**
-         * The date and time of the most recent user report for the incident.
-         */
-        lastReportTime?: Date;
         /**
          * Average speed within the incident area, in km/h.
          */
@@ -9170,7 +9146,7 @@ export declare type TrafficIncidentsModuleFeature = Omit<MapGeoJSONFeature, 'pro
         /**
          * Whether the incident is currently active or expected in the future.
          */
-        timeValidity?: TimeValidity;
+        timeValidity?: TrafficIncidentTimeValidity;
         /**
          * Positive integer ranking the importance of the road where the incident occurs.
          */