@tomtom-org/maps-sdk 0.49.0 → 0.50.0

package/core/dist/index.d.ts

@@ -1771,6 +1771,14 @@ export declare type CurrentType = (typeof currentTypes)[number];
  */
 export declare const currentTypes: readonly ["AC1", "AC3", "DC"];
 
+/**
+ * Default base URL for TomTom APIs. A `commonBaseURL` other than this signals a
+ * proxy or custom backend.
+ *
+ * @group Configuration
+ */
+export declare const DEFAULT_COMMON_BASE_URL = "https://api.tomtom.com";
+
 /**
  * Default global configuration values.
  *
@@ -3126,6 +3134,30 @@ export declare type Instruction = {
  */
 export declare const isBBoxWithArea: (bbox: OptionalBBox) => boolean;
 
+/**
+ * Whether the SDK is configured for a Demo-BFF-style proxy — no `apiKey` (the
+ * proxy injects the real key server-side from a cookie-gated session) plus a
+ * non-default `commonBaseURL`.
+ *
+ * In this mode SDK requests attach `credentials: 'include'` so the proxy's
+ * session cookie travels with them. In all other cases — direct TomTom usage
+ * and customer-owned `customServiceBaseURL` integrations — credentials stay at
+ * the browser default, so we don't break consumers whose backend responds with
+ * `Access-Control-Allow-Origin: *` (the browser rejects credentialed responses
+ * against a wildcard origin). A customer using `customServiceBaseURL` keeps a
+ * real `apiKey`, so this stays false for them.
+ *
+ * The `apiKey` test is a falsy check (not `=== ''`) on purpose: a proxy build
+ * may overwrite the bootstrap's `apiKey: ''` with `apiKey: undefined` (e.g.
+ * `put({ apiKey: process.env.API_KEY_EXAMPLES })` when that env var is unset).
+ * Both empty string and undefined mean "no key, the proxy injects it" — matching
+ * how the URL builders decide whether to append `key=` (`if (apiKey)`).
+ *
+ * @param config - Config to inspect; defaults to the global {@link TomTomConfig}.
+ * @group Configuration
+ */
+export declare const isProxyCredentialsMode: (config?: Partial<Pick<GlobalConfig, "apiKey" | "commonBaseURL">>) => boolean;
+
 /**
  * Type of landmarks that can be used in instructions.
  * @group Route

package/map/dist/index.d.ts

@@ -3461,14 +3461,8 @@ export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = Featu
  * Custom styling:
  * ```typescript
  * const geometriesModule = await GeometriesModule.get(map, {
- *   colorConfig: {
- *     fillColor: '#FF5733',
- *     fillOpacity: 0.3
- *   },
- *   lineConfig: {
- *     lineColor: '#C70039',
- *     lineWidth: 3
- *   },
+ *   fill: { color: '#FF5733', opacity: 0.3 },
+ *   line: { color: '#C70039', width: 3 },
  *   textConfig: {
  *     textField: ['get', 'name']
  *   }
@@ -3535,10 +3529,10 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      *
      * @remarks
      * **Configuration Options:**
-     * - `colorConfig`: Fill color and opacity settings
-     * - `lineConfig`: Border/outline styling
+     * - `fill`: Fill color, opacity, and optional fill-layer positioning
+     * - `line`: Border/outline styling and optional border-layer positioning
      * - `textConfig`: Label display configuration
-     * - `beforeLayerConfig`: Layer ordering (place above/below other layers)
+     * - `beforeLayerConfig`: Layer ordering — a single target, or `{ all, fill, line }` to split them
      *
      * **Multiple Instances:**
      * You can create multiple GeometriesModule instances on the same map,
@@ -3554,15 +3548,8 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * With custom styling:
      * ```typescript
      * const geometriesModule = await GeometriesModule.get(map, {
-     *   colorConfig: {
-     *     fillColor: 'blue',
-     *     fillOpacity: 0.25
-     *   },
-     *   lineConfig: {
-     *     lineColor: 'darkblue',
-     *     lineWidth: 2,
-     *     lineOpacity: 0.8
-     *   },
+     *   fill: { color: 'blue', opacity: 0.25 },
+     *   line: { color: 'darkblue', width: 2, opacity: 0.8 },
      *   textConfig: {
      *     textField: ['get', 'title']
      *   },
@@ -3574,9 +3561,9 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * Data-driven styling:
      * ```typescript
      * const geometriesModule = await GeometriesModule.get(map, {
-     *   colorConfig: {
+     *   fill: {
      *     // Color based on feature properties
-     *     fillColor: [
+     *     color: [
      *       'match',
      *       ['get', 'type'],
      *       'residential', '#FFEB3B',
@@ -3584,7 +3571,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      *       'industrial', '#9E9E9E',
      *       '#E0E0E0' // default
      *     ],
-     *     fillOpacity: 0.4
+     *     opacity: 0.4
      *   }
      * });
      * ```
@@ -3599,35 +3586,37 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * @ignore
      */
     protected _applyConfig(config: GeometriesModuleConfig | undefined): GeometriesModuleConfig | undefined;
-    private moveBeforeLayerID;
+    /** Resolve a positioning target to the map-style layer id the geometry layers should sit before. */
+    private resolveBeforeID;
+    private moveLayersBefore;
+    private get fillLayerIDs();
+    private get lineLayerIDs();
     /**
      * Positions the geometry layers relative to other map layers.
      *
-     * @param layerConfig - Layer positioning configuration.
-     * Can be `'top'` to place above all layers, or a specific layer ID.
+     * @param layerConfig - Layer positioning. A single {@link BeforeLayerConfig} (`'top'` or a layer
+     * id) moves all geometry layers together; the object form (`{ all?, fill?, line? }`) positions the
+     * fill and border independently.
      *
      * @remarks
-     * **Use Cases:**
-     * - Place geometries above base map but below labels
-     * - Ensure geometries appear above/below specific features
-     * - Control visual hierarchy of multiple data layers
+     * A per-layer `beforeLayerConfig` set inside the `fill` / `line` config sections takes precedence
+     * over the value passed here.
      *
-     * **Available Layer IDs:**
-     * Use predefined layer IDs from `mapStyleLayerIDs` or custom layer IDs.
+     * **Available Layer IDs:** predefined ids from `mapStyleLayerIDs`, or a custom layer id.
      *
      * @example
      * ```typescript
      * import { mapStyleLayerIDs } from '@tomtom-international/maps-sdk-js/map';
      *
-     * // Place below labels
+     * // Place all geometry layers below labels
      * geometries.moveBeforeLayer(mapStyleLayerIDs.lowestLabel);
      *
-     * // Place on top
-     * geometries.moveBeforeLayer('top');
+     * // Fill below the road network, border on top
+     * geometries.moveBeforeLayer({ fill: 'lowestRoadLine', line: 'top' });
      * ```
      */
     moveBeforeLayer(layerConfig: GeometryBeforeLayerConfig): void;
-    private _moveBeforeLayer;
+    private applyBeforeLayerConfig;
     /**
      * Updates the text/label configuration for displayed geometries.
      *
@@ -3818,26 +3807,14 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
  * ```typescript
  * // Basic styling
  * const config: GeometriesModuleConfig = {
- *   colorConfig: {
- *     fillColor: '#FF5733',
- *     fillOpacity: 0.3
- *   },
- *   lineConfig: {
- *     lineColor: '#C70039',
- *     lineWidth: 2
- *   }
+ *   fill: { color: '#FF5733', opacity: 0.3 },
+ *   line: { color: '#C70039', width: 2 },
  * };
  *
  * // With labels and positioning
  * const advancedConfig: GeometriesModuleConfig = {
- *   colorConfig: {
- *     fillColor: 'blue',
- *     fillOpacity: 0.25
- *   },
- *   lineConfig: {
- *     lineColor: 'darkblue',
- *     lineWidth: 3
- *   },
+ *   fill: { color: 'blue', opacity: 0.25 },
+ *   line: { color: 'darkblue', width: 3 },
  *   textConfig: {
  *     textField: ['get', 'name']
  *   },
@@ -3846,13 +3823,12 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
  *
  * // Data-driven styling
  * const dynamicConfig: GeometriesModuleConfig = {
- *   colorConfig: {
- *     fillColor: ['match', ['get', 'category'], 'park', '#4CAF50', 'water', '#2196F3', '#9E9E9E'],
- *     fillOpacity: 0.4
+ *   fill: {
+ *     color: ['match', ['get', 'category'], 'park', '#4CAF50', 'water', '#2196F3', '#9E9E9E'],
+ *     opacity: 0.4
  *   },
- *   lineConfig: {
- *     lineColor: '#000000',
- *     lineWidth: ['case', ['get', 'highlighted'], 4, 2]
+ *   line: {
+ *     color: '#000000', width: ['case', ['get', 'highlighted'], 4, 2],
  *   },
  *   textConfig: {
  *     textField: ['concat', ['get', 'name'], '\n', ['get', 'area'], ' km²']
@@ -3864,11 +3840,11 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
  */
 export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
     /**
-     * Fill color and opacity configuration.
+     * Fill color, opacity, and (optional) fill-layer positioning.
      *
      * Controls the interior color and transparency of polygon geometries.
      */
-    colorConfig?: GeometryColorConfig;
+    fill?: GeometryFillConfig;
     /**
      * Text label configuration.
      *
@@ -3876,11 +3852,11 @@ export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
      */
     textConfig?: GeometryTextConfig;
     /**
-     * Border/outline configuration.
+     * Border/outline configuration, and (optional) border-layer positioning.
      *
      * Controls the outline appearance of polygon geometries.
      */
-    lineConfig?: GeometryLineConfig;
+    line?: GeometryLineConfig;
     /**
      * Layer positioning configuration.
      *
@@ -3921,7 +3897,7 @@ export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
      * // Show the "rest of the world" outside a country
      * const module = await GeometriesModule.get(map, {
      *     theme: 'inverted',
-     *     colorConfig: { fillColor: 'black', fillOpacity: 0.5 }
+     *     fill: { color: 'black', opacity: 0.5 }
      * });
      * module.show(countryGeometry);
      * ```
@@ -3937,7 +3913,7 @@ export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
      * @remarks
      * Used internally by {@link reachableRangeGeometryConfig} to generate budget
      * labels (e.g. `'30 min'`) from feature properties. For most use cases,
-     * the standard config fields (`colorConfig`, `textConfig`, `theme`) suffice.
+     * the standard config fields (`fill`, `textConfig`, `theme`) suffice.
      *
      * @example
      * ```typescript
@@ -3965,113 +3941,110 @@ export declare type GeometriesModuleConfig = MapModuleCommonConfig & {
  * Use this to ensure geometries appear above or below other map features like
  * labels, roads, or other data layers.
  *
+ * @remarks
+ * A single {@link BeforeLayerConfig} (`'top'` or a layer id) positions **all** geometry layers
+ * together. The object form positions the fill and border independently — `all` is the fallback
+ * for any target it doesn't name.
+ *
  * @example
  * ```typescript
- * // Place on top of all layers
+ * // Place all geometry layers on top
  * const beforeLayer: GeometryBeforeLayerConfig = 'top';
  *
- * // Place below labels
+ * // Place all below labels
  * const beforeLayer: GeometryBeforeLayerConfig = 'lowestLabel';
+ *
+ * // Fill below the road network, border on top
+ * const beforeLayer: GeometryBeforeLayerConfig = { fill: 'lowestRoadLine', line: 'top' };
  * ```
  *
  * @group Geometries
  */
-export declare type GeometryBeforeLayerConfig = BeforeLayerConfig;
+export declare type GeometryBeforeLayerConfig = BeforeLayerConfig | GeometryBeforeLayerTargets;
 
 /**
- * Color configuration for geometry fill styling.
+ * Per-layer positioning targets for the object form of {@link GeometryBeforeLayerConfig}.
  *
- * Controls the fill color and opacity of polygon geometries displayed on the map.
+ * `fill` and `line` position their respective layers; `all` is the fallback applied to any
+ * target not explicitly set. A per-layer `beforeLayerConfig` inside {@link GeometryFillConfig}
+ * or {@link GeometryLineConfig} wins over the value here.
+ *
+ * @group Geometries
+ */
+export declare type GeometryBeforeLayerTargets = {
+    /** Fallback position for any layer not named by `fill` / `line`. */
+    all?: BeforeLayerConfig;
+    /** Position for the fill layer. */
+    fill?: BeforeLayerConfig;
+    /** Position for the border/outline layer (and its line labels). */
+    line?: BeforeLayerConfig;
+};
+
+/**
+ * Fill configuration for geometry styling — the interior color, opacity, and (optionally) where the
+ * fill layer sits in the map's layer stack.
  *
  * @example
  * ```typescript
  * // Solid color with opacity
- * const colorConfig: GeometryColorConfig = {
- *   fillColor: '#FF5733',
- *   fillOpacity: 0.3
- * };
+ * const fill: GeometryFillConfig = { color: '#FF5733', opacity: 0.3 };
  *
- * // Using color palette
- * const paletteConfig: GeometryColorConfig = {
- *   fillColor: 'red',  // Color palette name
- *   fillOpacity: 0.25
- * };
+ * // Palette name
+ * const fill: GeometryFillConfig = { color: 'red', opacity: 0.25 };
  *
  * // Data-driven color based on properties
- * const dynamicConfig: GeometryColorConfig = {
- *   fillColor: ['match', ['get', 'type'], 'residential', '#FFEB3B', 'commercial', '#2196F3', '#E0E0E0'],
- *   fillOpacity: 0.4
+ * const fill: GeometryFillConfig = {
+ *   color: ['match', ['get', 'type'], 'residential', '#FFEB3B', 'commercial', '#2196F3', '#E0E0E0'],
+ *   opacity: 0.4,
  * };
  * ```
  *
  * @group Geometries
  */
-export declare type GeometryColorConfig = {
+export declare type GeometryFillConfig = {
     /**
-     * Fill color for the geometry.
-     *
-     * @remarks
-     * Can be:
-     * - Hex color string (e.g., `'#FF5733'`)
-     * - Color palette name (e.g., `'red'`, `'blue'`)
-     * - MapLibre expression for data-driven styling
+     * Fill color: a hex string (`'#FF5733'`), a palette name (`'red'`), or a MapLibre expression
+     * for data-driven styling (e.g. `['get', 'color']`).
      *
      * @default '#0A3653'
-     *
-     * @example
-     * ```typescript
-     * // Hex color
-     * fillColor: '#FF5733'
-     *
-     * // Palette name
-     * fillColor: 'red'
-     *
-     * // MapLibre expression
-     * fillColor: ['get', 'color']
-     *
-     * // Conditional coloring
-     * fillColor: ['case', ['>', ['get', 'area'], 10000], '#FF0000', '#00FF00']
-     * ```
      */
-    fillColor?: ColorPaletteOptions | DataDrivenPropertyValueSpecification<string>;
+    color?: ColorPaletteOptions | DataDrivenPropertyValueSpecification<string>;
     /**
-     * Opacity of the fill color.
-     *
-     * @remarks
-     * Value between 0 (fully transparent) and 1 (fully opaque).
+     * Fill opacity, 0 (transparent) to 1 (opaque). Also accepts a MapLibre expression.
      *
      * @default 0.15
+     */
+    opacity?: DataDrivenPropertyValueSpecification<number>;
+    /**
+     * Layer positioning for the **fill** layer only.
      *
-     * @example
-     * ```typescript
-     * fillOpacity: 0.5  // 50% transparent
-     *
-     * // Data-driven opacity
-     * fillOpacity: ['interpolate', ['linear'], ['get', 'importance'], 1, 0.8, 10, 0.3]
-     * ```
+     * @remarks
+     * Overrides the top-level {@link GeometriesModuleConfig.beforeLayerConfig} for the fill.
+     * Use this to sink the fill below the road network while the border stays above, e.g.
+     * `fill: { beforeLayerConfig: 'lowestRoadLine' }`, `line: { beforeLayerConfig: 'top' }`.
      */
-    fillOpacity?: DataDrivenPropertyValueSpecification<number>;
+    beforeLayerConfig?: BeforeLayerConfig;
 };
 
 /**
- * Line/border configuration for geometries.
+ * Line/border configuration for geometries — the outline color, opacity, width, an escape hatch for
+ * any other line property, and (optionally) where the border layer sits in the map's layer stack.
  *
- * Controls the outline appearance of polygon geometries.
+ * @remarks
+ * The curated `color` / `opacity` / `width` fields cover the common cases; the {@link
+ * GeometryLineConfig.layer | `layer`} escape hatch accepts a partial MapLibre `LineLayerSpecification`
+ * for anything else (`line-gap-width`, `line-cap`, `line-join`, …). The curated fields take precedence
+ * over the same `paint` property set via `layer`.
  *
  * @example
  * ```typescript
- * // Basic border
- * const lineConfig: GeometryLineConfig = {
- *   lineColor: '#333333',
- *   lineWidth: 2,
- *   lineOpacity: 0.8
- * };
+ * // Curated fields
+ * const line: GeometryLineConfig = { color: '#333333', width: 2, opacity: 0.8 };
  *
  * // Data-driven border
- * const dynamicLine: GeometryLineConfig = {
- *   lineColor: ['get', 'borderColor'],
- *   lineWidth: ['case', ['get', 'selected'], 4, 2],
- *   lineOpacity: 1
+ * const line: GeometryLineConfig = {
+ *   color: ['get', 'borderColor'],
+ *   width: ['case', ['get', 'selected'], 4, 2],
  * };
  * ```
  *
@@ -4079,45 +4052,54 @@ export declare type GeometryColorConfig = {
  */
 export declare type GeometryLineConfig = {
     /**
-     * Color of the geometry border/outline.
+     * Border/outline color: a hex string or a MapLibre expression (e.g. `['get', 'borderColor']`).
      *
      * @default '#0A3653'
+     */
+    color?: DataDrivenPropertyValueSpecification<string>;
+    /**
+     * Border opacity, 0 (transparent) to 1 (opaque). Also accepts a MapLibre expression.
      *
-     * @example
-     * ```typescript
-     * lineColor: '#333333'
-     * lineColor: ['get', 'borderColor']
-     * ```
+     * @default 1
+     */
+    opacity?: DataDrivenPropertyValueSpecification<number>;
+    /**
+     * Border width in pixels. Also accepts a MapLibre expression
+     * (e.g. `['case', ['get', 'selected'], 4, 2]`).
+     *
+     * @default 2
      */
-    lineColor?: DataDrivenPropertyValueSpecification<string>;
+    width?: DataDrivenPropertyValueSpecification<number>;
     /**
-     * Opacity of the border line.
+     * Escape hatch for full control over the border (outline) line layer.
      *
      * @remarks
-     * Value between 0 (fully transparent) and 1 (fully opaque).
+     * Accepts a partial MapLibre `LineLayerSpecification` (without `id`/`source`) that is merged
+     * onto the outline layer: top-level fields first, then `layout` and `paint` are merged per
+     * property so base defaults survive. Use this to set any line property the curated fields above
+     * don't cover (e.g. `line-gap-width`, `line-cap`, `line-join`, `line-pattern`).
      *
-     * @default 1
+     * The curated fields (`color`, `opacity`, `width`) **take precedence** over the same `paint`
+     * properties set here.
      *
      * @example
      * ```typescript
-     * lineOpacity: 0.8
+     * line: {
+     *     color: '#00A65E',
+     *     layer: { paint: { 'line-gap-width': 3 }, layout: { 'line-cap': 'round' } },
+     * }
      * ```
      */
-    lineOpacity?: DataDrivenPropertyValueSpecification<number>;
+    layer?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
     /**
-     * Width of the border line in pixels.
+     * Layer positioning for the **border/outline** layer only.
      *
-     * @default 2
-     *
-     * @example
-     * ```typescript
-     * lineWidth: 3
-     *
-     * // Highlight selected geometries
-     * lineWidth: ['case', ['get', 'selected'], 4, 2]
-     * ```
+     * @remarks
+     * Overrides the top-level {@link GeometriesModuleConfig.beforeLayerConfig} for the border.
+     * Pair with {@link GeometryFillConfig.beforeLayerConfig} to split the fill and border across
+     * the layer stack (e.g. fill below roads, border on top).
      */
-    lineWidth?: DataDrivenPropertyValueSpecification<number>;
+    beforeLayerConfig?: BeforeLayerConfig;
 };
 
 /**