@tomtom-org/maps-sdk 0.47.0 → 0.47.1

package/core/dist/index.d.ts

@@ -2144,6 +2144,34 @@ export declare interface FeatureCollectionWithProperties<G extends Geometry | nu
  */
 export declare const findBestWaypointInsertionIndex: (route: Route, existingWaypoints: WaypointLike[], newWaypoint: WaypointLike) => number;
 
+/**
+ * Multi-waypoint variant of {@link findBestWaypointInsertionIndex}.
+ *
+ * Projects every existing and new waypoint onto the route exactly once, then returns one
+ * insertion slot per new waypoint. The i-th returned index is the slot in `existingWaypoints`
+ * (0 = before origin, `existingWaypoints.length` = after destination) where the i-th new
+ * waypoint falls based on its along-route location.
+ *
+ * Multiple new waypoints may share the same slot. Use {@link withInsertedWaypoints} when you
+ * also need them merged into the existing array in correct along-route order — that helper
+ * handles within-slot ranking on top of these slot indices.
+ *
+ * @param route The existing calculated route Feature with LineString geometry
+ * @param existingWaypoints Array of existing waypoints in order (origin, intermediate waypoints, destination)
+ * @param newWaypoints The waypoints whose insertion slots to compute
+ * @returns An array of insertion slot indices, one per new waypoint, in input order
+ *
+ * @remarks
+ * - Empty `newWaypoints` returns an empty array.
+ * - Edge cases (empty route geometry, fewer than 2 existing waypoints) return `0` for every
+ *   new waypoint — i.e. they would all prepend.
+ * - A new waypoint whose projection has no resolvable along-route location also returns `0`,
+ *   matching the singular {@link findBestWaypointInsertionIndex} behavior.
+ *
+ * @group Utils
+ */
+export declare const findBestWaypointInsertionIndices: (route: Route, existingWaypoints: WaypointLike[], newWaypoints: WaypointLike[]) => number[];
+
 /**
  * Formatting is based on the number of meters passed and unit type. Less meters more precision.
  * @example
@@ -2260,6 +2288,22 @@ export declare const formatDuration: (seconds: number | undefined, options?: Tim
  */
 export declare type Fuel = 'Petrol' | 'LPG' | 'Diesel' | 'Biodiesel' | 'DieselForCommercialVehicles' | 'E85' | 'LNG' | 'CNG' | 'Hydrogen' | 'AdBlue';
 
+/**
+ * All possible traffic incident categories.
+ *
+ * @remarks
+ * Composed of {@link trafficIncidentRequestCategories} (categories that can be both
+ * sent as filter inputs and received in responses) plus the response-only categories
+ * `'animals-on-road'` and `'narrow-lanes'`, which appear in API responses and on
+ * vector-tile features but are rejected as `categoryFilter` inputs. Use this list
+ * when a category can be *received*; use {@link trafficIncidentRequestCategories}
+ * when a category must be *sent* to the Incident Details API as a `categoryFilter`
+ * input.
+ *
+ * @group Traffic
+ */
+export declare const fullTrafficIncidentCategories: readonly ["accident", "broken-down-vehicle", "danger", "flooding", "fog", "frost", "jam", "lane-closed", "other", "rain", "road-closed", "roadworks", "wind", "animals-on-road", "narrow-lanes"];
+
 /**
  * Generate random id for map features
  * @ignore
@@ -5043,12 +5087,6 @@ export declare type TrafficIncidentBaseProperties = {
     lastReportTime?: Date;
 };
 
-/**
- * All possible traffic incident categories.
- * @group Traffic
- */
-export declare const trafficIncidentCategories: readonly ["accident", "animals-on-road", "broken-down-vehicle", "danger", "flooding", "fog", "frost", "jam", "lane-closed", "narrow-lanes", "other", "rain", "road-closed", "roadworks", "wind"];
-
 /**
  * Simple category classification for traffic incidents.
  *
@@ -5071,7 +5109,7 @@ export declare const trafficIncidentCategories: readonly ["accident", "animals-o
  *
  * @group Traffic
  */
-export declare type TrafficIncidentCategory = (typeof trafficIncidentCategories)[number];
+export declare type TrafficIncidentCategory = (typeof fullTrafficIncidentCategories)[number];
 
 /**
  * Response from the Incident Details service.
@@ -5157,6 +5195,34 @@ export declare type TrafficIncidentProperties = TrafficIncidentBaseProperties &
     tmc?: TrafficIncidentTMC;
 };
 
+/**
+ * Traffic incident categories accepted as `categoryFilter` inputs by the Incident
+ * Details API.
+ *
+ * @remarks
+ * Strict subset of {@link fullTrafficIncidentCategories} — every value here is also
+ * a valid response category. The two values omitted (`'animals-on-road'` and
+ * `'narrow-lanes'`) are documented as response-only: the upstream's default-values
+ * list is `0,1,2,3,4,5,6,7,8,9,10,11,14`, intentionally excluding iconCategory 12
+ * and 13. Including either makes the upstream reject the whole filter with
+ * `Unsupported categoryFilter parameter value`.
+ *
+ * @see https://docs.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/traffic-incidents/incident-details
+ * @group Traffic
+ */
+export declare const trafficIncidentRequestCategories: readonly ["accident", "broken-down-vehicle", "danger", "flooding", "fog", "frost", "jam", "lane-closed", "other", "rain", "road-closed", "roadworks", "wind"];
+
+/**
+ * Categories accepted as `categoryFilter` input to the Incident Details API.
+ *
+ * @remarks
+ * Strict subset of {@link TrafficIncidentCategory} — see
+ * {@link trafficIncidentRequestCategories} for the rationale.
+ *
+ * @group Traffic
+ */
+export declare type TrafficIncidentRequestCategory = (typeof trafficIncidentRequestCategories)[number];
+
 /**
  * Traffic incident information based on TPEG2-TEC standard.
  *
@@ -5514,4 +5580,44 @@ export declare type Waypoints<T extends Anything = Anything> = FeatureCollection
  */
 export declare const withInsertedWaypoint: (route: Route, existingWaypoints: WaypointLike[], newWaypoint: WaypointLike) => WaypointLike[];
 
+/**
+ * Returns a new array of waypoints with each new waypoint inserted at its optimal position.
+ *
+ * Multi-waypoint variant of {@link withInsertedWaypoint}. Unlike a sequential one-at-a-time
+ * insertion, this function projects every existing and new waypoint onto the route exactly
+ * once, then merges them by:
+ *
+ * 1. Computing each new waypoint's insertion slot via {@link findBestWaypointInsertionIndices}.
+ * 2. Within each slot, ranking the new waypoints by their along-route location (with a stable
+ *    tie-break on input order when multiple waypoints project to the same location).
+ *
+ * The result is the existing waypoints with newcomers spliced in at the right positions and in
+ * natural along-route order — accurate regardless of input order.
+ *
+ * @param route The existing calculated route Feature with LineString geometry
+ * @param existingWaypoints Array of existing waypoints in order (origin, intermediate waypoints, destination)
+ * @param newWaypoints The waypoints to insert
+ * @returns A new array with the waypoints inserted at their optimal positions
+ *
+ * @remarks
+ * - Returns a new array; does not modify the original `existingWaypoints` array.
+ * - Passing an empty `newWaypoints` array returns a shallow copy of `existingWaypoints`.
+ * - When the route has no geometry or fewer than 2 existing waypoints, all new waypoints are
+ *   prepended in input order.
+ *
+ * @example
+ * ```typescript
+ * const waypoints: WaypointLike[] = [
+ *   [4.9, 52.3],   // origin
+ *   [5.0, 52.4]    // destination
+ * ];
+ *
+ * const updated = withInsertedWaypoints(route, waypoints, [[4.97, 52.37], [4.93, 52.33]]);
+ * // → [[4.9, 52.3], [4.93, 52.33], [4.97, 52.37], [5.0, 52.4]]
+ * ```
+ *
+ * @group Utils
+ */
+export declare const withInsertedWaypoints: (route: Route, existingWaypoints: WaypointLike[], newWaypoints: WaypointLike[]) => WaypointLike[];
+
 export { }