@tomtom-org/maps-sdk 0.38.1 → 0.40.0

package/core/dist/index.d.ts

@@ -389,7 +389,7 @@ export declare const bboxFromCoordsArray: (coordinates: Position[] | undefined)
  * // Returns bbox encompassing all three places
  * ```
  *
- * @group Shared
+ * @group Utils
  */
 export declare const bboxFromGeoJSON: (hasBBox: HasBBox) => OptionalBBox;
 
@@ -1665,7 +1665,7 @@ export declare type DistanceDisplayUnits = {
  * const ukSystem: DistanceUnitsType = 'imperial_uk';  // United Kingdom
  * ```
  *
- * @group Shared
+ * @group Utils
  */
 export declare type DistanceUnitsType = 'metric' | 'imperial_us' | 'imperial_uk';
 
@@ -1878,7 +1878,7 @@ export declare interface FeatureCollectionWithProperties<G extends Geometry | nu
  * ```
  * @param meters
  * @param options Options for the display units, including their type and custom ways to display them.
- * @group Shared
+ * @group Utils
  */
 export declare const formatDistance: (meters: number, options?: DistanceDisplayUnits) => string;
 
@@ -1933,7 +1933,7 @@ export declare const formatDistance: (meters: number, options?: DistanceDisplayU
  * // Output: "Estimated time: 2 hr 15 min"
  * ```
  *
- * @group Shared
+ * @group Utils
  */
 export declare const formatDuration: (seconds: number | undefined, options?: TimeDisplayUnits) => string | undefined;
 
@@ -2082,7 +2082,7 @@ export declare type GeometryDataSource = {
  * getPosition(undefined); // Returns: null
  * ```
  *
- * @group Shared
+ * @group Utils
  */
 export declare const getPosition: (hasLngLat: HasLngLat | undefined, options?: GetPositionOptions) => Position | null;
 
@@ -3562,6 +3562,12 @@ export declare type PolygonFeatures<P = GeoJsonProperties> = Omit<FeatureCollect
     bbox?: BBox;
 };
 
+/**
+ * Creates a GeoJSON Polygon Feature representing the area of the given bounding box.
+ * @param bbox The bounding box defined as [west, south, east, north]
+ */
+export declare const polygonFromBBox: (bbox: BBox) => Feature<Polygon>;
+
 /**
  * Possible directions a lane can lead to.
  *

package/map/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { Anything } from '@tomtom-org/maps-sdk/core';
 import { BackgroundLayerSpecification } from 'maplibre-gl';
 import { BBox } from '@tomtom-org/maps-sdk/core';
+import { BBox as BBox_2 } from '@tomtom-org/maps-sdk/core';
+import { BBox as BBox_3 } from '@tomtom-org/maps-sdk/core';
 import { ChargingSpeed } from '@tomtom-org/maps-sdk/core';
 import { ChargingStop } from '@tomtom-org/maps-sdk/core';
 import { CircleLayerSpecification } from 'maplibre-gl';
@@ -33,6 +35,7 @@ import { Places as Places_2 } from '@tomtom-org/maps-sdk/core';
 import { POICategory } from '@tomtom-org/maps-sdk/core';
 import { Point } from 'geojson';
 import { PolygonFeatures } from '@tomtom-org/maps-sdk/core';
+import { Position } from 'geojson';
 import { Route } from '@tomtom-org/maps-sdk/core';
 import { RouteProps } from '@tomtom-org/maps-sdk/core';
 import { Routes } from '@tomtom-org/maps-sdk/core';
@@ -989,6 +992,88 @@ export declare type ByIdOrIndex = {
     index: number;
 };
 
+/**
+ * Calculates an expanded bounding box that, when the map is zoomed to it, ensures that the given to-be-contained bounding box
+ * is visible within the area not obscured by surrounding UI elements, including optional padding.
+ * * In other words, calculates a bounding box that ensure the to-be-contained bbox fits within the visible area of the map.
+ *
+ * @remarks
+ * This is useful when you have a specific geographic area (containedBBox) that you want to be fully visible
+ * in the unobscured portion of the map (the area not covered by UI components).
+ * The function returns a larger bounding box that accounts for the space taken by UI elements.
+ *
+ * @param options - The options for calculating expanded bounds
+ * @returns The expanded bounding box as [west, south, east, north], or null if the visible area is too small
+ *
+ * @group Utils
+ */
+export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox_2 | null;
+
+/**
+ * Options for calculating expanded bounds.
+ *
+ * @group Utils
+ */
+export declare type CalculateFittingBBoxOptions = CalculateMapBoundsOptions & {
+    /**
+     * The target bounding box [west, south, east, north] that should be contained in the unobscured area
+     */
+    toBeContainedBBox: BBox_3;
+};
+
+/**
+ * Options for calculating map bounds.
+ *
+ * @group Utils
+ */
+export declare type CalculateMapBoundsOptions = CalculateMapCenterOptions & {
+    /**
+     * Additional padding in pixels to apply around the UI elements or map edges. Default is 0.
+     */
+    paddingPX?: number;
+};
+
+/**
+ * Options for calculating map center.
+ *
+ * @group Utils
+ */
+export declare type CalculateMapCenterOptions = {
+    /** The TomTomMap instance or MapLibre map instance */
+    map: TomTomMap | Map_2;
+    /** Array of HTML elements or DOM selector strings that are positioned over the map */
+    surroundingElements: (HTMLElement | string)[];
+};
+
+/**
+ * Calculates the bounding box in lng-lat coordinates of the visible map area
+ * that does not overlap with the given UI HTML elements.
+ *
+ * @remarks
+ * This is useful for determining the area of the map that is not obscured by UI components.
+ *
+ * @param options - The options for calculating map bounds
+ * @returns The padded bounding box as [west, south, east, north], or null if the visible area is too small
+ *
+ * @group Utils
+ */
+export declare const calculatePaddedBBox: (options: CalculateMapBoundsOptions) => BBox_2 | null;
+
+/**
+ * Calculates the center point in lng-lat coordinates of the visible map area
+ * that does not overlap with the given UI HTML elements.
+ *
+ * @remarks
+ * * This is useful to offset the map center in a way that it looks harmonious with surrounding UI components.
+ * * It's equivalent to the center of calculatePaddedBBox.
+ *
+ * @param options - The options for calculating map center
+ * @returns The center as [lng, lat], or null if the visible area is too small
+ *
+ * @group Utils
+ */
+export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions) => Position | null;
+
 /**
  * Mapping of charging stop speeds to sprite image IDs.
  * @group Routing