@tomtom-org/maps-sdk 0.61.0 → 0.62.0

package/core/dist/index.d.ts

@@ -2178,6 +2178,128 @@ type RelatedPOI = {
   id: string;
 };
 //#endregion
+//#region src/types/reachableRange.d.ts
+/**
+ * Every {@link BudgetType}, to list them in a picker or validate one.
+ *
+ * @group Reachable Range
+ */
+export declare const budgetTypes: readonly ["timeMinutes", "remainingChargePCT", "spentChargePCT", "spentFuelLiters", "distanceKM"];
+/**
+ * Type of budget constraint for reachable range calculation.
+ *
+ * @remarks
+ * **Budget Types:**
+ * - `timeMinutes`: Travel time in minutes (isochrone)
+ * - `distanceKM`: Travel distance in kilometers (isodistance)
+ * - `remainingChargePCT`: Remaining battery charge in percentage (EV)
+ * - `spentChargePCT`: Battery charge consumed in percentage (EV)
+ * - `spentFuelLiters`: Fuel consumed in liters (combustion)
+ *
+ * Both charge budgets are converted against the battery capacity, so they need an electric
+ * `vehicle` with `model.engine.charging.maxChargeKWH`; `remainingChargePCT` also needs its current
+ * charge in `vehicle.state`.
+ *
+ * **Common Use Cases:**
+ * - Time: "Where can I reach in 30 minutes?"
+ * - Distance: "What's within 10 km?"
+ * - EV charge: "How far can I go on 50% battery?"
+ * - Fuel: "Range with 20 liters of fuel"
+ *
+ * @example
+ * ```typescript
+ * const timeType: BudgetType = 'timeMinutes';
+ * const distanceType: BudgetType = 'distanceKM';
+ * const evType: BudgetType = 'remainingChargePCT';
+ * ```
+ *
+ * @group Reachable Range
+ */
+export type BudgetType = (typeof budgetTypes)[number];
+/**
+ * Budget constraint for reachable range calculation.
+ *
+ * Defines the limit (time, distance, or fuel/charge) for calculating
+ * how far you can travel from a starting point.
+ *
+ * @remarks
+ * **Use Cases:**
+ * - Service area visualization (30-min delivery zone)
+ * - EV range anxiety mitigation (show reachable area)
+ * - Emergency response coverage (10-min response time)
+ * - Delivery zone planning
+ * - Store location analysis
+ *
+ * @example
+ * ```typescript
+ * // 30-minute travel time
+ * const timeBudget: ReachableRangeBudget = {
+ *   type: 'timeMinutes',
+ *   value: 30
+ * };
+ *
+ * // 50 km distance
+ * const distanceBudget: ReachableRangeBudget = {
+ *   type: 'distanceKM',
+ *   value: 50
+ * };
+ *
+ * // 50% battery remaining
+ * const evBudget: ReachableRangeBudget = {
+ *   type: 'remainingChargePCT',
+ *   value: 50
+ * };
+ *
+ * // 20 liters of fuel
+ * const fuelBudget: ReachableRangeBudget = {
+ *   type: 'spentFuelLiters',
+ *   value: 20
+ * };
+ * ```
+ *
+ * @group Reachable Range
+ */
+export type ReachableRangeBudget = {
+  /**
+   * The type of budget, including units. See {@link BudgetType}.
+   */
+  type: BudgetType;
+  /**
+   * The value of the budget based on the units mentioned in the type.
+   *
+   * @remarks
+   * **Typical Values:**
+   * - Time: 5-60 minutes
+   * - Distance: 5-100 km
+   * - Charge: 10-100 percentage
+   * - Fuel: 5-50 liters
+   *
+   * @example
+   * ```typescript
+   * value: 30    // 30 minutes/km/percent/liters depending on type
+   * value: 15.5  // Decimal values supported
+   * ```
+   */
+  value: number;
+};
+/**
+ * The unit each {@link BudgetType} counts in, to print next to a budget value: `30 min`, `20 % remaining`.
+ *
+ * @example
+ * ```typescript
+ * const label = `${budget.value} ${budgetUnits[budget.type]}`;
+ * ```
+ *
+ * @group Reachable Range
+ */
+export declare const budgetUnits: {
+  readonly timeMinutes: "min";
+  readonly distanceKM: "km";
+  readonly remainingChargePCT: "% remaining";
+  readonly spentChargePCT: "% spent";
+  readonly spentFuelLiters: "L";
+};
+//#endregion
 //#region src/types/route/chargingStop.d.ts
 /**
  * Available plug types for EV charging.