@tomtom-org/maps-sdk 0.57.0 → 0.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import { AllLayoutProperties, AllPaintProperties, BackgroundLayerSpecification, CircleLayerSpecification, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, FilterSpecification, GeoJSONSource, GeoJSONSourceSpecification, LayerSpecification, LineLayerSpecification, LngLat, Map, MapGeoJSONFeature, MapOptions, Source, SourceSpecification, StyleImageInterface, StyleImageMetadata, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
2
- import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, ChargingSpeed, ChargingStop, ChargingStopProps, CommonPlaceProps, CountrySectionProps, DelayMagnitude, DisplayUnits, GetPositionEntryPointOption, GlobalConfig, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, RouteProps, Routes, SectionProps, SectionType, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
2
+ import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, ChargingSpeed, ChargingStop, ChargingStopProps, CommonPlaceProps, CountrySectionProps, DelayMagnitude, DisplayUnits, EntryPoint, GetPositionEntryPointOption, GlobalConfig, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, RouteProps, Routes, SectionProps, SectionType, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
3
3
  //#region src/shared/types/style.d.ts
4
4
  /**
5
5
  * Indicator of a light or dark theme.
@@ -27,7 +27,8 @@ type LightDark = 'light' | 'dark';
27
27
  * precisionMode: 'box',
28
28
  * paddingBoxPx: 5,
29
29
  * cursorOnHover: 'pointer',
30
- * longHoverDelayOnStillMapMS: 300
30
+ * longHoverDelayOnStillMapMS: 300,
31
+ * hoverGracePeriodMS: 400
31
32
  * };
32
33
  *
33
34
  * // Mobile-optimized with larger hit area
@@ -46,7 +47,7 @@ type LightDark = 'light' | 'dark';
46
47
  *
47
48
  * @group User Interaction Events
48
49
  */
49
- type MapEventsConfig = EventHandlerCursorConfig & {
50
+ type MapEventsConfig = EventHandlerConfig & {
50
51
  /**
51
52
  * Optional configuration to show custom cursor when clicking (mouse down).
52
53
  *
@@ -547,20 +548,12 @@ export type TomTomMapParams = Partial<GlobalConfig> & {
547
548
  */
548
549
  style?: StyleInput;
549
550
  /**
550
- * Event handler configuration for map interactions.
551
- *
552
- * Define callbacks for various map events like clicks, hovers, and movements.
551
+ * How user events are detected and timed, and which cursors they show, for every module.
552
+ * Change it later with {@link TomTomMap.updateEventsConfig}.
553
553
  *
554
554
  * @example
555
555
  * ```typescript
556
- * events: {
557
- * onClick: (event) => {
558
- * console.log('Clicked at', event.lngLat);
559
- * },
560
- * onMoveEnd: () => {
561
- * console.log('Map moved to', map.getCenter());
562
- * }
563
- * }
556
+ * events: { paddingBoxPx: 10, longHoverDelayOnStillMapMS: 500, hoverGracePeriodMS: 1000 }
564
557
  * ```
565
558
  */
566
559
  events?: MapEventsConfig;
@@ -1161,6 +1154,22 @@ export declare class TomTomMap {
1161
1154
  * @see {@link https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes | ISO 639-1 Language Codes}
1162
1155
  */
1163
1156
  setLanguage(language: Language): void;
1157
+ /**
1158
+ * Changes the map's user events configuration at runtime.
1159
+ *
1160
+ * @param config Merged into the current configuration, set at construction through
1161
+ * {@link TomTomMapParams.events}: what it leaves out, or sets `undefined`, keeps its value.
1162
+ *
1163
+ * @remarks
1164
+ * A module's own `events` config still overrides the cursor and `hoverGracePeriodMS` for its
1165
+ * features. A long hover or a grace period already running keeps the delay it started with.
1166
+ *
1167
+ * @example
1168
+ * ```typescript
1169
+ * map.updateEventsConfig({ longHoverDelayOnStillMapMS: 600, hoverGracePeriodMS: 1000 });
1170
+ * ```
1171
+ */
1172
+ updateEventsConfig(config: MapEventsConfig): void;
1164
1173
  /**
1165
1174
  * Retrieves the current visible map area as a GeoJSON bounding box.
1166
1175
  *
@@ -1777,8 +1786,13 @@ export type GeoJSONSourceClusterOptions = Pick<GeoJSONSourceSpecification, 'clus
1777
1786
  */
1778
1787
  export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
1779
1788
  shownFeatures: T;
1789
+ private readonly showListeners;
1780
1790
  constructor(map: Map, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean, clusterOptions?: GeoJSONSourceClusterOptions);
1781
1791
  show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
1792
+ /**
1793
+ * Calls `listener` after every `show`, including the ones an event-state change makes.
1794
+ */
1795
+ onShow(listener: () => void): void;
1782
1796
  /**
1783
1797
  * Canonical id-based lookup into `shownFeatures.features` via {@link findFeatureByRefId}
1784
1798
  * (first match wins on duplicate ids). Returns `undefined` for a nullish or absent id.
@@ -2059,6 +2073,18 @@ type HoverEventType = 'hover' | 'hover-move' | 'long-hover';
2059
2073
  * @group User Interaction Events
2060
2074
  */
2061
2075
  type EventType = ClickEventType | HoverEventType;
2076
+ /**
2077
+ * The state a feature carries in `properties.eventState`: the user event it is in, or
2078
+ * `recently-hovered` for a moment after the pointer leaves it.
2079
+ *
2080
+ * @remarks
2081
+ * `recently-hovered` lasts {@link EventHandlerHoverConfig.hoverGracePeriodMS}, then clears on its own
2082
+ * unless the feature is hovered or clicked again first. The SDK's own layers draw it as no state;
2083
+ * read it to keep something shown while the pointer travels, as the entry points of places do.
2084
+ *
2085
+ * @group User Interaction Events
2086
+ */
2087
+ type EventState = EventType | 'recently-hovered';
2062
2088
  /**
2063
2089
  * Parameters to identify a feature by its ID or index in a given features array.
2064
2090
  * @group User Interaction Events
@@ -2239,7 +2265,7 @@ type CleanEventStatesOptions = {
2239
2265
  * states: ['click', 'contextmenu', 'hover', 'long-hover']
2240
2266
  * ```
2241
2267
  */
2242
- states?: EventType[];
2268
+ states?: EventState[];
2243
2269
  /**
2244
2270
  * Whether to show the feature after cleaning the event state.
2245
2271
  *
@@ -2286,11 +2312,12 @@ type SupportsEvents = {
2286
2312
  * @remarks
2287
2313
  * - `undefined`: No active event state (normal appearance)
2288
2314
  * - Event type: Active state that affects styling and behavior
2315
+ * - `recently-hovered`: The pointer just left the feature; see {@link EventState}
2289
2316
  *
2290
2317
  * This property is automatically managed by the SDK based on user
2291
2318
  * interactions and programmatic state changes.
2292
2319
  */
2293
- eventState?: EventType;
2320
+ eventState?: EventState;
2294
2321
  };
2295
2322
  /**
2296
2323
  * Handler function for user interaction events on map features.
@@ -2387,103 +2414,66 @@ type EventHandlerCursorConfig = {
2387
2414
  */
2388
2415
  cursorOnHover?: CSSCursor;
2389
2416
  };
2417
+ /**
2418
+ * Event configuration options related to hover states.
2419
+ *
2420
+ * @group User Interaction Events
2421
+ */
2422
+ type EventHandlerHoverConfig = {
2423
+ /**
2424
+ * How long, in milliseconds, a feature stays `recently-hovered` after the pointer leaves it.
2425
+ * `0` clears its state at once.
2426
+ *
2427
+ * @remarks
2428
+ * Set on the map (`events` of the map parameters) for every module, or on one module's
2429
+ * `events` config to override it there.
2430
+ *
2431
+ * @default 400
2432
+ */
2433
+ hoverGracePeriodMS?: number;
2434
+ };
2390
2435
  /**
2391
2436
  * Optional events configuration for a map module.
2392
2437
  *
2393
2438
  * @group User Interaction Events
2394
2439
  */
2395
- type EventHandlerConfig = EventHandlerCursorConfig;
2440
+ type EventHandlerConfig = EventHandlerCursorConfig & EventHandlerHoverConfig;
2396
2441
  //#endregion
2397
2442
  //#region src/shared/types/filters.d.ts
2398
2443
  /**
2399
- * Filter mode determining whether to include or exclude specified values.
2400
- *
2401
- * @remarks
2402
- * Controls how the values list is interpreted:
2403
- * - `all_except`: Show everything except the specified values (exclusion mode)
2404
- * - `only`: Show only the specified values, hide everything else (inclusion mode)
2405
- *
2406
- * @example
2407
- * ```typescript
2408
- * // Exclusion mode
2409
- * const mode: FilterShowMode = 'all_except';
2410
- *
2411
- * // Inclusion mode
2412
- * const mode: FilterShowMode = 'only';
2413
- * ```
2444
+ * Every {@link FilterShowMode}, for validating one at runtime.
2414
2445
  *
2415
2446
  * @group Shared
2416
2447
  */
2417
- type FilterShowMode = 'all_except' | 'only';
2448
+ export declare const filterShowModes: readonly ["only", "all-except"];
2418
2449
  /**
2419
- * Generic filter configuration for showing or hiding items by value.
2420
- *
2421
- * Provides a flexible way to control visibility of categorized items (e.g., POI categories,
2422
- * layer groups, road types) using either inclusion or exclusion mode.
2423
- *
2424
- * @typeParam T - The type of values being filtered (e.g., string literals, enums)
2450
+ * How a {@link ValuesFilter} reads its `values`:
2451
+ * - `only`: show only these values, hide everything else
2452
+ * - `all-except`: show everything except these values
2425
2453
  *
2426
- * @remarks
2427
- * **Filter Modes:**
2428
- * - `only`: Whitelist mode - only specified values are shown
2429
- * - `all_except`: Blacklist mode - all values except specified ones are shown
2454
+ * @group Shared
2455
+ */
2456
+ export type FilterShowMode = (typeof filterShowModes)[number];
2457
+ /**
2458
+ * Shows or hides items by value — POI categories, traffic road categories, incident magnitudes.
2430
2459
  *
2431
- * **Common Use Cases:**
2432
- * - Filtering POI categories (show only restaurants)
2433
- * - Hiding map layer groups (hide all except roads)
2434
- * - Filtering traffic incidents by type
2435
- * - Controlling road categories in traffic flow
2460
+ * @typeParam T - The type of values being filtered
2436
2461
  *
2437
2462
  * @example
2438
2463
  * ```typescript
2439
- * // Show only specific categories
2440
- * const includeFilter: ValuesFilter<string> = {
2441
- * show: 'only',
2442
- * values: ['RESTAURANT', 'CAFE', 'BAR']
2443
- * };
2444
- *
2445
- * // Hide specific categories
2446
- * const excludeFilter: ValuesFilter<string> = {
2447
- * show: 'all_except',
2448
- * values: ['PARKING_GARAGE']
2449
- * };
2464
+ * // Show only these categories
2465
+ * const includeFilter: ValuesFilter<string> = { show: 'only', values: ['RESTAURANT', 'CAFE', 'BAR'] };
2450
2466
  *
2451
- * // Type-safe with string literals
2452
- * type RoadType = 'motorway' | 'trunk' | 'primary';
2453
- * const roadFilter: ValuesFilter<RoadType> = {
2454
- * show: 'only',
2455
- * values: ['motorway', 'trunk']
2456
- * };
2467
+ * // Hide these categories
2468
+ * const excludeFilter: ValuesFilter<string> = { show: 'all-except', values: ['PARKING_GARAGE'] };
2457
2469
  * ```
2458
2470
  *
2459
2471
  * @group Shared
2460
2472
  */
2461
- type ValuesFilter<T> = {
2462
- /**
2463
- * Filter mode determining whether values list is inclusive or exclusive.
2464
- *
2465
- * @remarks
2466
- * - `only`: Shows only the items in the values array (whitelist)
2467
- * - `all_except`: Shows all items except those in the values array (blacklist)
2468
- */
2473
+ export type ValuesFilter<T> = {
2474
+ /** Whether `values` is the set to show or the set to hide. */
2469
2475
  show: FilterShowMode;
2470
- /**
2471
- * Array of values to include or exclude based on the show mode.
2472
- *
2473
- * @remarks
2474
- * The interpretation of this array depends on the `show` property:
2475
- * - If `show` is `'only'`, only these values will be visible
2476
- * - If `show` is `'all_except'`, these values will be hidden
2477
- *
2478
- * @example
2479
- * ```typescript
2480
- * // Include only these values
2481
- * values: ['RESTAURANT', 'HOTEL']
2482
- *
2483
- * // Exclude these values
2484
- * values: ['PARKING']
2485
- * ```
2486
- */
2476
+ /** The values to show or hide, depending on `show`. */
2487
2477
  values: T[];
2488
2478
  };
2489
2479
  //#endregion
@@ -2535,9 +2525,9 @@ type CustomImage<I extends string = string> = {
2535
2525
  *
2536
2526
  * This ID is used to reference the icon when styling map features.
2537
2527
  * The specific values depend on the context:
2538
- * - For POI categories: Use MapStylePOICategory values (e.g., 'RESTAURANT', 'HOTEL_MOTEL')
2528
+ * - For POI categories: Use MapStylePOICategory values (e.g., 'RESTAURANT', 'HOTEL_OR_MOTEL')
2539
2529
  * - For route waypoints: Use waypoint identifiers (e.g., 'waypoint-start', 'waypoint-end')
2540
- * - For charging stations: Use station type identifiers (e.g., 'ELECTRIC_VEHICLE_STATION')
2530
+ * - For charging stations: Use station type identifiers (e.g., 'CHARGING_LOCATION')
2541
2531
  * - For custom markers: Use any unique string identifier
2542
2532
  */
2543
2533
  id: I;
@@ -2605,12 +2595,12 @@ type CustomImage<I extends string = string> = {
2605
2595
  * // Define custom icons for both availability states
2606
2596
  * categoryIcons: [
2607
2597
  * {
2608
- * id: 'ELECTRIC_VEHICLE_STATION',
2598
+ * id: 'CHARGING_LOCATION',
2609
2599
  * image: greenChargingSVG,
2610
2600
  * availabilityLevel: 'available'
2611
2601
  * },
2612
2602
  * {
2613
- * id: 'ELECTRIC_VEHICLE_STATION',
2603
+ * id: 'CHARGING_LOCATION',
2614
2604
  * image: redChargingSVG,
2615
2605
  * availabilityLevel: 'occupied'
2616
2606
  * }
@@ -3090,14 +3080,20 @@ export declare class EventsProxy extends AbstractEventProxy {
3090
3080
  private hoveringFeatures?;
3091
3081
  private hoveringSourceWithLayers?;
3092
3082
  private longHoverTimeoutHandlerID?;
3083
+ private readonly recentHoverTimeouts;
3093
3084
  private firstDelayedHoverSinceMapMove;
3094
3085
  private lastClickedFeature?;
3095
3086
  private lastClickedSourceWithLayers?;
3096
3087
  private lastCursorStyle;
3097
3088
  private pendingMouseMove?;
3098
3089
  private mouseMoveFrameRequested;
3099
- private readonly config;
3090
+ private config;
3100
3091
  constructor(map: Map, config?: MapEventsConfig);
3092
+ /**
3093
+ * Merges `config` into the current configuration; what it leaves out, or sets `undefined`,
3094
+ * keeps its value. Timers already running keep the delay they started with.
3095
+ */
3096
+ updateConfig(config: MapEventsConfig): void;
3101
3097
  private listenToEvents;
3102
3098
  enable(enabled: boolean): void;
3103
3099
  private toPaddedBounds;
@@ -3143,6 +3139,8 @@ export declare class EventsProxy extends AbstractEventProxy {
3143
3139
  private dispatchHoverEnter;
3144
3140
  private dispatchHoverMove;
3145
3141
  private dispatchToHandlers;
3142
+ private hoverGracePeriodFor;
3143
+ private clearRecentHoverLater;
3146
3144
  private updateHoverCursor;
3147
3145
  private onMapClick;
3148
3146
  }
@@ -4112,9 +4110,8 @@ export declare abstract class AbstractStyleOwnedMapModule<SOURCES_WITH_LAYERS ex
4112
4110
  * The kind of value a display knob takes.
4113
4111
  *
4114
4112
  * @remarks
4115
- * One vocabulary for every knob catalogue in the SDK — map styling and any module that describes
4116
- * its display as knobs draw from the same set, so an agent that learned one catalogue can read the
4117
- * other.
4113
+ * One vocabulary for every knob catalogue in the SDK and its plugins, so a UI or an agent that
4114
+ * learned one catalogue can read the other.
4118
4115
  *
4119
4116
  * - `toggle`: `true`/`false`, e.g. whether an overlay is drawn.
4120
4117
  * - `factor`: a multiplier over what the style already does (`1` = unchanged).
@@ -4137,77 +4134,6 @@ export type KnobRange = {
4137
4134
  max: number;
4138
4135
  step?: number;
4139
4136
  };
4140
- /**
4141
- * A single, machine-readable description of one display knob.
4142
- *
4143
- * @remarks
4144
- * The point of describing knobs as data is that a caller — increasingly a coding agent rather than
4145
- * a person reading docs — can ask what a module actually exposes instead of guessing layer ids from
4146
- * training data. Three things follow from having it:
4147
- *
4148
- * - **ground before generating** — write against what the module exposes, not what you remember;
4149
- * - **validate** — ranges and allowed values arrive as data, so a bad value is caught before it
4150
- * is rendered;
4151
- * - **report and diff** — the paired settings object is plain and serializable, so a display change
4152
- * is reviewable in a pull request.
4153
- *
4154
- * A visual editor cannot do any of those: it cannot be read, diffed, or put in a pull request.
4155
- *
4156
- * Modules narrow this shape with their own descriptor type — e.g. `StylingKnobDescriptor` requires
4157
- * `available` and `appliesTo`, while a module whose knobs are always applicable omits them.
4158
- *
4159
- * @group Shared
4160
- */
4161
- export type KnobDescriptor<T = unknown> = {
4162
- /**
4163
- * Stable, dotted identifier, e.g. `labels.sizeFactor`. Treat these as public API: they are what
4164
- * a caller stores, diffs and passes back.
4165
- */
4166
- id: string;
4167
- /** What kind of value the knob takes. */
4168
- kind: KnobKind;
4169
- /** One-line description of what turning this knob does. */
4170
- description: string;
4171
- /** The value in force when nothing has been configured. */
4172
- default: T;
4173
- /** The value in force now. */
4174
- current: T;
4175
- /** Whether {@link KnobDescriptor.current} came from configuration rather than the default. */
4176
- overridden: boolean;
4177
- /** Inclusive bounds, for `factor` and `number` knobs. */
4178
- range?: KnobRange;
4179
- /** The allowed values, for `enum` knobs; the names accepted besides CSS colours, for `colors` knobs. */
4180
- options?: readonly string[];
4181
- /**
4182
- * Whether the knob has anything to work on in the loaded style. Omitted by modules whose knobs
4183
- * are always applicable; set to `false` by modules where a knob can be present in the catalogue
4184
- * but do nothing on the current style.
4185
- */
4186
- available?: boolean;
4187
- /**
4188
- * Which styles or contexts the knob works in. A string rather than a fixed union so each
4189
- * module can choose its own vocabulary — styling uses `'any-style' | 'tomtom-styles'`.
4190
- */
4191
- appliesTo?: string;
4192
- };
4193
- /**
4194
- * Builds one knob descriptor, working out `overridden` from whether a configured value was given.
4195
- * Pass `available` / `appliesTo` / `range` / `options` through `extra` when the module uses them.
4196
- * @ignore
4197
- */
4198
- export declare const knob: <T, ID extends string, KIND extends KnobKind, Extra extends object = Record<string, never>>(id: ID, kind: KIND, description: string, defaultValue: T, configured: T | undefined, extra?: Extra) => KnobDescriptor<T> & {
4199
- id: ID;
4200
- kind: KIND;
4201
- } & Extra;
4202
- /**
4203
- * Reduces a knob catalogue to a plain, serializable object of the values in force.
4204
- *
4205
- * @remarks
4206
- * Only knobs whose value was configured are included, so the result is a diff against the defaults
4207
- * rather than a dump of everything — which is what makes it reviewable.
4208
- * @ignore
4209
- */
4210
- export declare const knobSettings: (knobs: KnobDescriptor[]) => Record<string, unknown>;
4211
4137
  //#endregion
4212
4138
  //#region src/shared/layers/commonLayerProps.d.ts
4213
4139
  /**
@@ -4742,6 +4668,10 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
4742
4668
  * buildings, labels, and other vector tile layers from the base map style.
4743
4669
  *
4744
4670
  * @remarks
4671
+ * **What this module owns:** whether each base-map layer group is shown. How the base map looks is
4672
+ * {@link StylingModule} knobs, whose `basemap.<group>` and `buildings.*` toggles switch the same groups.
4673
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
4674
+ *
4745
4675
  * **Managed Layers:**
4746
4676
  * - Background and land cover
4747
4677
  * - Water bodies and coastlines
@@ -6222,18 +6152,12 @@ export declare class GeometriesModule extends AbstractDataOwnedMapModule<Geometr
6222
6152
  * ```
6223
6153
  *
6224
6154
  * @example
6225
- * From search API response:
6155
+ * From a place's geometry:
6226
6156
  * ```typescript
6227
- * import { search } from '@tomtom-org/maps-sdk/services';
6157
+ * import { geocodeOne, geometryData } from '@tomtom-org/maps-sdk/services';
6228
6158
  *
6229
- * const result = await search.geometrySearch({
6230
- * query: 'Amsterdam',
6231
- * geometryList: [{ type: 'CIRCLE', position: [52.37, 4.89], radius: 5000 }]
6232
- * });
6233
- *
6234
- * if (result.results[0].dataSources?.geometry) {
6235
- * await geometries.show(result.results[0].dataSources.geometry);
6236
- * }
6159
+ * const amsterdam = await geocodeOne('Amsterdam');
6160
+ * await geometries.show(await geometryData({ geometries: [amsterdam] }));
6237
6161
  * ```
6238
6162
  */
6239
6163
  show(geometries: PolygonFeatures): Promise<void>;
@@ -6723,6 +6647,45 @@ export type PlaceDisplayProps = {
6723
6647
  */
6724
6648
  export type DisplayPlaceProps = CommonPlaceProps & PlaceDisplayProps;
6725
6649
  //#endregion
6650
+ //#region src/places/types/entryPointDisplay.d.ts
6651
+ /**
6652
+ * Properties of an entry point drawn by {@link PlacesModule}: the {@link EntryPoint} itself, whose
6653
+ * position is the feature geometry, plus where it came from.
6654
+ *
6655
+ * @group Places
6656
+ */
6657
+ type PlaceEntryPointProps = Omit<EntryPoint, 'position'> & {
6658
+ /**
6659
+ * Unique identifier of the entry point feature, derived from its place.
6660
+ */
6661
+ id: string;
6662
+ /**
6663
+ * `id` of the place the entry point belongs to, as shown by the module.
6664
+ */
6665
+ placeID: string;
6666
+ /**
6667
+ * Index of the entry point in the `entryPoints` of its place.
6668
+ */
6669
+ entryPointIndex: number;
6670
+ } & SupportsEvents;
6671
+ /**
6672
+ * What `places.events.entryPoints` handlers receive: the entry point as a point feature, whether its
6673
+ * circle or its line was hit, together with the place it belongs to.
6674
+ *
6675
+ * @remarks
6676
+ * The place is passed as shown, with its own geometry. To route to the entrance, pass this feature
6677
+ * as the route location.
6678
+ *
6679
+ * @group Places
6680
+ */
6681
+ type PlaceEntryPointFeature = Feature<Point, PlaceEntryPointProps & {
6682
+ /**
6683
+ * The place the entry point belongs to. Absent only when that place left the map while the
6684
+ * event was being handled.
6685
+ */
6686
+ place?: Place<DisplayPlaceProps>;
6687
+ }>;
6688
+ //#endregion
6726
6689
  //#region src/places/types/placesModuleConfig.d.ts
6727
6690
  /**
6728
6691
  * Icon style options for displaying places on the map.
@@ -6765,7 +6728,7 @@ export declare const placesThemes: readonly ["pin", "circle-icon", "base-map", "
6765
6728
  * const places = await PlacesModule.create(map, {
6766
6729
  * evAvailability: { enabled: true }
6767
6730
  * });
6768
- * const stations = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
6731
+ * const stations = await discoverPlaces({ poiCategories: ['CHARGING_LOCATION'] });
6769
6732
  * places.show(await getPlacesWithEVAvailability(stations));
6770
6733
  *
6771
6734
  * // Custom threshold and format
@@ -6781,7 +6744,7 @@ export declare const placesThemes: readonly ["pin", "circle-icon", "base-map", "
6781
6744
  * const places = await PlacesModule.create(map, {
6782
6745
  * icon: {
6783
6746
  * categoryIcons: [{
6784
- * id: 'ELECTRIC_VEHICLE_STATION',
6747
+ * id: 'CHARGING_LOCATION',
6785
6748
  * image: customEvIconSvg,
6786
6749
  * pixelRatio: 2
6787
6750
  * }]
@@ -6865,7 +6828,7 @@ type DefaultPlaceIconConfig = {
6865
6828
  * const iconConfig: PlaceIconConfig = {
6866
6829
  * categoryIcons: [
6867
6830
  * { category: 'RESTAURANT', image: '/icons/food.png', pixelRatio: 2 },
6868
- * { category: 'HOTEL_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }
6831
+ * { category: 'HOTEL_OR_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }
6869
6832
  * ]
6870
6833
  * };
6871
6834
  * ```
@@ -7280,6 +7243,81 @@ type PlaceConnectionsConfig = {
7280
7243
  */
7281
7244
  layers?: PlaceConnectionsLayersConfig;
7282
7245
  };
7246
+ /**
7247
+ * Which shown places get their entry points drawn.
7248
+ *
7249
+ * @remarks
7250
+ * - `all`: every place that has entry points.
7251
+ * - `selected`: hovered or clicked places, the ones the `selected` layer highlights. A
7252
+ * `recently-hovered` place counts too, so the pointer can cross the map to an entrance.
7253
+ * - `clicked`: clicked places, which stay clicked until the next click lands elsewhere.
7254
+ *
7255
+ * `selected` and `clicked` follow the module's event states, which exist once an event handler is
7256
+ * registered on the module or {@link PlacesModule.putEventState} is called. Hovering or clicking an
7257
+ * entry point keeps the entry points of its place drawn when a handler covers them: one on `events`
7258
+ * or `events.entryPoints`, not on `events.places` alone.
7259
+ *
7260
+ * @group Places
7261
+ */
7262
+ type PlaceEntryPointsShowFor = 'all' | 'selected' | 'clicked';
7263
+ /**
7264
+ * MapLibre layer customization for entry points.
7265
+ *
7266
+ * @remarks
7267
+ * The layer IDs are derived from the PlacesModule instance prefix:
7268
+ * - `point`: a circle on each entry point, larger for a `main` one than for the rest
7269
+ * - `line`: a dotted line from the place to each of its entry points
7270
+ *
7271
+ * @group Places
7272
+ */
7273
+ type PlaceEntryPointsLayersConfig = {
7274
+ /**
7275
+ * Entry point circle layer specification.
7276
+ */
7277
+ point?: Partial<ToBeAddedLayerSpecTemplate<CircleLayerSpecification>>;
7278
+ /**
7279
+ * Place-to-entry-point line layer specification.
7280
+ */
7281
+ line?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
7282
+ };
7283
+ /**
7284
+ * Configuration for drawing the entry points (entrances) of the shown places.
7285
+ *
7286
+ * @remarks
7287
+ * Draws `properties.entryPoints` of each place, whichever service returned it.
7288
+ *
7289
+ * @example
7290
+ * ```typescript
7291
+ * const places = await PlacesModule.create(map, {
7292
+ * entryPoints: { showFor: 'clicked', minZoom: 16 }
7293
+ * });
7294
+ * // The handler is what makes places clickable, and so what lets them reach the `click` state.
7295
+ * places.events.on('click', (feature) => console.log(feature.properties.title));
7296
+ * ```
7297
+ *
7298
+ * @group Places
7299
+ */
7300
+ type PlaceEntryPointsConfig = {
7301
+ /**
7302
+ * Which places get their entry points drawn.
7303
+ *
7304
+ * @default 'selected'
7305
+ */
7306
+ showFor?: PlaceEntryPointsShowFor;
7307
+ /**
7308
+ * Zoom level below which no entry point is drawn.
7309
+ *
7310
+ * @remarks
7311
+ * Under the `pin-clustered` theme it is never lower than 18, the first zoom without clusters.
7312
+ *
7313
+ * @default 15
7314
+ */
7315
+ minZoom?: number;
7316
+ /**
7317
+ * Custom MapLibre layer specifications for the entry point circles and lines.
7318
+ */
7319
+ layers?: PlaceEntryPointsLayersConfig;
7320
+ };
7283
7321
  /**
7284
7322
  * Configuration options for the PlacesModule.
7285
7323
  *
@@ -7374,6 +7412,13 @@ type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModu
7374
7412
  * (a dashed line) and no label.
7375
7413
  */
7376
7414
  connections?: PlaceConnectionsConfig;
7415
+ /**
7416
+ * Configuration for drawing the entry points of the shown places.
7417
+ *
7418
+ * @remarks
7419
+ * When omitted, entry points are not drawn.
7420
+ */
7421
+ entryPoints?: PlaceEntryPointsConfig;
7377
7422
  /**
7378
7423
  * Additional properties to compute for each place feature.
7379
7424
  *
@@ -7442,6 +7487,14 @@ type ConnectionFeatureProps = {
7442
7487
  */
7443
7488
  type ConnectionFeatureCollection = FeatureCollection<LineString, ConnectionFeatureProps>;
7444
7489
  //#endregion
7490
+ //#region src/places/utils/prepareEntryPointsForDisplay.d.ts
7491
+ /**
7492
+ * Each entry point is two features sharing one id: its circle, then its line. The circle comes
7493
+ * first, so an id lookup (event states, event payloads) always lands on it.
7494
+ * @ignore
7495
+ */
7496
+ type EntryPointFeatureCollection = FeatureCollection<Point | LineString, PlaceEntryPointProps>;
7497
+ //#endregion
7445
7498
  //#region src/places/PlacesModule.d.ts
7446
7499
  type PlacesSourcesAndLayers = {
7447
7500
  /**
@@ -7463,6 +7516,10 @@ type PlacesSourcesAndLayers = {
7463
7516
  * Connections source id with corresponding layers ids (line + label).
7464
7517
  */
7465
7518
  connections: GeoJSONSourceWithLayers<ConnectionFeatureCollection>;
7519
+ /**
7520
+ * Entry points source id with corresponding layers ids (line + point).
7521
+ */
7522
+ entryPoints: GeoJSONSourceWithLayers<EntryPointFeatureCollection>;
7466
7523
  };
7467
7524
  /**
7468
7525
  * What {@link PlacesModule.show} accepts, and what `shown-features` handlers receive back.
@@ -7492,14 +7549,19 @@ export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig,
7492
7549
  places: UserEvents<Place<DisplayPlaceProps>>;
7493
7550
  /** The lines and labels connecting places to their parent, when connections are shown. */
7494
7551
  connections: UserEvents<MapGeoJSONFeature>;
7552
+ /** The entry points of places, when {@link PlacesModuleConfig.entryPoints} draws them. */
7553
+ entryPoints: UserEvents<PlaceEntryPointFeature>;
7495
7554
  };
7496
7555
  export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
7497
7556
  private layerSpecs;
7498
7557
  private connectionLayerSpecs;
7558
+ private entryPointLayerSpecs;
7559
+ private refreshingEntryPoints;
7499
7560
  private currentClusterMode;
7500
7561
  private sourceID;
7501
7562
  private unclusteredSourceID;
7502
7563
  private connectionSourceID;
7564
+ private entryPointSourceID;
7503
7565
  private layerIDPrefix;
7504
7566
  private defaultPlaceIconID;
7505
7567
  private shownConnections;
@@ -7521,10 +7583,13 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
7521
7583
  * @ignore
7522
7584
  */
7523
7585
  protected _initSourcesWithLayers(config?: PlacesModuleConfig, restore?: boolean): PlacesSourcesAndLayers;
7586
+ private addOverlaySource;
7587
+ private replaceLayerSpecs;
7524
7588
  private partitionSpecsForSources;
7525
7589
  private buildLayerSpecs;
7526
7590
  private buildClusterOptions;
7527
7591
  private buildConnectionLayerSpecs;
7592
+ private buildEntryPointLayerSpecs;
7528
7593
  /**
7529
7594
  * @ignore
7530
7595
  */
@@ -7629,8 +7694,9 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
7629
7694
  applyExtraFeatureProps<P extends CommonPlaceProps = CommonPlaceProps>(extraFeatureProps: NonNullable<PlacesModuleConfig<P>['extraFeatureProps']>): void;
7630
7695
  private updateLayersAndData;
7631
7696
  private rebuildSourcesAndLayers;
7632
- private updateConnectionLayersAndData;
7633
7697
  private updateConnectionsData;
7698
+ private updateEntryPointsData;
7699
+ private applyLayersVisibility;
7634
7700
  private applyPlacesVisibility;
7635
7701
  private setupImages;
7636
7702
  private updateData;
@@ -7655,9 +7721,9 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
7655
7721
  * @example
7656
7722
  * Display search results:
7657
7723
  * ```typescript
7658
- * import { search } from '@tomtom-org/maps-sdk/services';
7724
+ * import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
7659
7725
  *
7660
- * const results = await search({ query: 'coffee' });
7726
+ * const results = await discoverPlaces({ query: 'coffee' });
7661
7727
  * await placesModule.show(results);
7662
7728
  * ```
7663
7729
  *
@@ -7971,13 +8037,13 @@ export type POICategoryGroup = keyof typeof poiCategoryGroups;
7971
8037
  /**
7972
8038
  * A POI classification or group that can be filtered.
7973
8039
  *
7974
- * Can be either a specific POI category (like RESTAURANT, HOTEL_MOTEL) or a
8040
+ * Can be either a specific POI category (like RESTAURANT, HOTEL_OR_MOTEL) or a
7975
8041
  * broader category group (like FOOD_DRINKS_GROUP, SHOPPING_GROUP) that contains
7976
8042
  * multiple related categories.
7977
8043
  *
7978
8044
  * @remarks
7979
8045
  * **Category vs Group:**
7980
- * - Category: Specific POI type (e.g., RESTAURANT, GAS_STATION)
8046
+ * - Category: Specific POI type (e.g., RESTAURANT, FUEL_STATION)
7981
8047
  * - Group: Collection of related categories (e.g., FOOD_DRINKS_GROUP includes restaurants, cafes, bars)
7982
8048
  *
7983
8049
  * Using groups is more convenient when you want to filter multiple related categories at once.
@@ -8024,7 +8090,7 @@ type FilterablePOICategory = MapStylePOICategory | POICategoryGroup;
8024
8090
  * const noParkingConfig: POIsModuleConfig = {
8025
8091
  * filters: {
8026
8092
  * categories: {
8027
- * show: 'all_except',
8093
+ * show: 'all-except',
8028
8094
  * values: ['PARKING_GROUP']
8029
8095
  * }
8030
8096
  * }
@@ -8058,25 +8124,20 @@ type POIsModuleConfig = MapModuleCommonConfig & {
8058
8124
  */
8059
8125
  filters?: {
8060
8126
  /**
8061
- * Category filter configuration.
8062
- *
8063
- * @remarks
8064
- * By default, all categories are included in the map.
8065
- * - Use `all_except` show mode to hide some categories/groups
8066
- * - Use `only` mode to show only specific categories/groups and hide everything else
8127
+ * Categories or category groups to show or hide, per {@link FilterShowMode}.
8067
8128
  *
8068
8129
  * @example
8069
8130
  * ```typescript
8070
8131
  * // Show only restaurants and hotels
8071
8132
  * categories: {
8072
8133
  * show: 'only',
8073
- * values: ['RESTAURANT', 'HOTEL_MOTEL']
8134
+ * values: ['RESTAURANT', 'HOTEL_OR_MOTEL']
8074
8135
  * }
8075
8136
  *
8076
8137
  * // Hide parking
8077
8138
  * categories: {
8078
- * show: 'all_except',
8079
- * values: ['PARKING_GARAGE', 'OPEN_PARKING_AREA']
8139
+ * show: 'all-except',
8140
+ * values: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA']
8080
8141
  * }
8081
8142
  *
8082
8143
  * // Show only food-related POIs
@@ -8139,7 +8200,7 @@ type POIsModuleFeature = Feature<Point, {
8139
8200
  *
8140
8201
  * @remarks
8141
8202
  * Used for styling and filtering purposes. Maps to a specific POI type
8142
- * (e.g., RESTAURANT, HOTEL_MOTEL).
8203
+ * (e.g., RESTAURANT, HOTEL_OR_MOTEL).
8143
8204
  *
8144
8205
  * @example 'restaurant'
8145
8206
  */
@@ -8191,6 +8252,10 @@ type PoIsSourcesAndLayers = {
8191
8252
  * and include businesses, landmarks, and other points of interest.
8192
8253
  *
8193
8254
  * @remarks
8255
+ * **What this module owns:** whether the style's POIs are shown, and which categories. Their size,
8256
+ * label colours and zoom thresholds are `pois.*` knobs on {@link StylingModule}.
8257
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
8258
+ *
8194
8259
  * **Features:**
8195
8260
  * - Toggle POI visibility on/off
8196
8261
  * - Filter by POI categories or category groups
@@ -8198,7 +8263,7 @@ type PoIsSourcesAndLayers = {
8198
8263
  * - Based on vector tile data in the map style
8199
8264
  *
8200
8265
  * **POI Categories:**
8201
- * - Individual categories (e.g., RESTAURANT, HOTEL_MOTEL, PARKING_GARAGE)
8266
+ * - Individual categories (e.g., RESTAURANT, HOTEL_OR_MOTEL, PARKING_GARAGE)
8202
8267
  * - Category groups (e.g., FOOD_DRINKS_GROUP, SHOPPING_GROUP, TRANSPORTATION_GROUP)
8203
8268
  *
8204
8269
  * **Difference from PlacesModule:**
@@ -8224,13 +8289,13 @@ type PoIsSourcesAndLayers = {
8224
8289
  * // Show only restaurants and hotels
8225
8290
  * poisModule.filterCategories({
8226
8291
  * show: 'only',
8227
- * values: ['RESTAURANT', 'HOTEL_MOTEL']
8292
+ * values: ['RESTAURANT', 'HOTEL_OR_MOTEL']
8228
8293
  * });
8229
8294
  *
8230
8295
  * // Hide parking garages
8231
8296
  * poisModule.filterCategories({
8232
- * show: 'all_except',
8233
- * values: ['PARKING_GARAGE', 'OPEN_PARKING_AREA']
8297
+ * show: 'all-except',
8298
+ * values: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA']
8234
8299
  * });
8235
8300
  * ```
8236
8301
  *
@@ -8245,7 +8310,7 @@ type PoIsSourcesAndLayers = {
8245
8310
  *
8246
8311
  * // Hide transportation POIs
8247
8312
  * pois.filterCategories({
8248
- * show: 'all_except',
8313
+ * show: 'all-except',
8249
8314
  * values: ['TRANSPORTATION_GROUP']
8250
8315
  * });
8251
8316
  * ```
@@ -8350,32 +8415,8 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
8350
8415
  /**
8351
8416
  * Filters POIs by category or category group.
8352
8417
  *
8353
- * @param categoriesFilter - Filter configuration specifying which categories to show/hide.
8354
- * Pass `undefined` to reset to default (show all).
8355
- *
8356
- * @remarks
8357
- * **Filter Modes:**
8358
- * - `only`: Show only the specified categories, hide all others
8359
- * - `all_except`: Show all categories except the specified ones
8360
- *
8361
- * **Category Types:**
8362
- * - Individual categories (e.g., 'RESTAURANT', 'HOTEL_MOTEL')
8363
- * - Category groups (e.g., 'FOOD_DRINKS_GROUP', 'SHOPPING_GROUP')
8364
- *
8365
- * **Available Category Groups:**
8366
- * - FOOD_DRINKS_GROUP
8367
- * - SHOPPING_GROUP
8368
- * - TRANSPORTATION_GROUP
8369
- * - HEALTH_GROUP
8370
- * - PARKING_GROUP
8371
- * - HOLIDAY_TOURISM_GROUP
8372
- * - EV_CHARGING_STATIONS_GROUP
8373
- * - GAS_STATIONS_GROUP
8374
- * - ACCOMMODATION_GROUP
8375
- * - ENTERTAINMENT_GROUP
8376
- * - SPORTS_LEISURE_GROUP
8377
- * - EDUCATION_GROUP
8378
- * - GOVERNMENT_GROUP
8418
+ * @param categoriesFilter - Categories (`'RESTAURANT'`) or {@link POICategoryGroup | groups}
8419
+ * (`'FOOD_DRINKS_GROUP'`) to show or hide, per {@link FilterShowMode}. `undefined` shows all.
8379
8420
  *
8380
8421
  * @example
8381
8422
  * Show only restaurants:
@@ -8390,7 +8431,7 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
8390
8431
  * Hide parking:
8391
8432
  * ```typescript
8392
8433
  * pois.filterCategories({
8393
- * show: 'all_except',
8434
+ * show: 'all-except',
8394
8435
  * values: ['PARKING_GROUP']
8395
8436
  * });
8396
8437
  * ```
@@ -9280,13 +9321,13 @@ type SectionIconConfig = {
9280
9321
  * - `center`: one icon at the middle of each section.
9281
9322
  * - `along`: icons repeated along the section.
9282
9323
  *
9283
- * @defaultValue `"center"`
9324
+ * @defaultValue `"center"` on the generated types; `ferry` and `tollRoad` keep their own placement.
9284
9325
  */
9285
9326
  placement?: 'center' | 'along';
9286
9327
  /**
9287
9328
  * Icon scale, where `1` is the sprite image's own size.
9288
9329
  *
9289
- * @defaultValue 1
9330
+ * @defaultValue `1` on the generated types; `ferry` and `tollRoad` keep their own zoom-ramped size.
9290
9331
  */
9291
9332
  size?: number;
9292
9333
  };
@@ -11038,10 +11079,10 @@ type StyleSources = Record<string, {
11038
11079
  //#endregion
11039
11080
  //#region src/styling/mapColorCatalogue.d.ts
11040
11081
  /**
11041
- * The ten semantic map colours — TomTom Map Maker's *Foundations* palette, under its own names and
11042
- * in its own order. One name drives every layer and shade the style derives from it.
11082
+ * The ten semantic map colours — the *Foundations* palette of TomTom's style themes, under their own
11083
+ * names and in their order. One name drives every layer and shade the style derives from it.
11043
11084
  *
11044
- * | Name | Map Maker | Reaches |
11085
+ * | Name | Theme label | Reaches |
11045
11086
  * |---|---|---|
11046
11087
  * | `land` | Land (base) | Map background and other bare-land features, influences admin borders/labels. Also used to derive all map colours if undefined. |
11047
11088
  * | `water` | Water | Waterbodies, waterways and other water features. Also influences glaciers, water labels and ferry lines. |
@@ -11078,7 +11119,7 @@ declare const paintColorProperties: readonly ["fill-color", "fill-outline-color"
11078
11119
  /** @ignore */
11079
11120
  type PaintColorProperty = (typeof paintColorProperties)[number];
11080
11121
  /**
11081
- * The ten map colour names, in Map Maker's Foundations order.
11122
+ * The ten map colour names, in the themes' Foundations order.
11082
11123
  *
11083
11124
  * @group Map Styling
11084
11125
  */
@@ -11160,6 +11201,13 @@ type StylingPresetId = keyof typeof stylingPresets;
11160
11201
  * @group Map Styling
11161
11202
  */
11162
11203
  export declare const stylingPresetIds: StylingPresetId[];
11204
+ /**
11205
+ * Every styling preset with its name, use case and the knob values it applies, in catalogue order.
11206
+ * Static data: no map is needed to read it.
11207
+ *
11208
+ * @group Map Styling
11209
+ */
11210
+ export declare const stylingPresetCatalogue: readonly StylingPreset[];
11163
11211
  //#endregion
11164
11212
  //#region src/styling/types/stylingTypes.d.ts
11165
11213
  /**
@@ -11208,57 +11256,31 @@ type StylingKnobRange = KnobRange & {
11208
11256
  step: number;
11209
11257
  };
11210
11258
  /**
11211
- * One entry of the styling catalogue returned by {@link StylingModule.describe}: everything a UI or
11212
- * an agent needs to offer the knob, validate a value for it and show its state.
11213
- *
11214
- * @remarks
11215
- * Narrows the shared {@link KnobDescriptor}: styling ids and value types are known, `range.step` is
11216
- * always given, and `available` / `appliesTo` are required — every styling knob answers both.
11259
+ * One entry of {@link stylingKnobCatalogue}: what a UI or a coding agent needs to offer the knob and
11260
+ * validate a value for it, with no map loaded. The value in force is {@link StylingModule.get}.
11217
11261
  *
11218
11262
  * @group Map Styling
11219
11263
  */
11220
- type StylingKnobDescriptor = KnobDescriptor & {
11264
+ type StylingKnob = {
11221
11265
  /** The knob's id, as accepted by {@link StylingModule.set}. */
11222
11266
  id: StylingKnobId;
11223
11267
  kind: StylingKnobKind;
11224
- /**
11225
- * The value the loaded style ships with. `undefined` when the style defines it as a data-driven
11226
- * expression that no single value stands for; `reset` still restores it exactly.
11227
- */
11228
- default: StylingKnobValue | undefined;
11229
- /** The value in effect right now: the override if there is one, otherwise the default. */
11230
- current: StylingKnobValue | undefined;
11268
+ /** One line on what turning the knob does. */
11269
+ description: string;
11231
11270
  /** The range of valid values, for `factor` and `number` knobs. */
11232
11271
  range?: StylingKnobRange;
11233
11272
  /** The valid values, for `enum` knobs. */
11234
11273
  options?: readonly string[];
11235
- /**
11236
- * Whether the knob has anything to work on in the loaded style. `false` means setting it would
11237
- * do nothing, and the SDK also warns once in the console when that happens. Check this before
11238
- * offering the knob in a UI or to an agent. Map-level knobs are always available.
11239
- */
11240
- available: boolean;
11241
11274
  /** Which styles the knob works on; see {@link stylingKnobAppliesTo}. */
11242
11275
  appliesTo: StylingKnobAppliesTo;
11243
11276
  };
11244
- /**
11245
- * The machine-readable styling catalogue: what can be styled on the loaded style, with defaults,
11246
- * ranges and current values. Additive across SDK minor versions; knob ids are public API.
11247
- *
11248
- * @group Map Styling
11249
- */
11250
- type StylingCatalogue = {
11251
- knobs: StylingKnobDescriptor[];
11252
- /** The presets {@link StylingModule.applyPreset} accepts, with the settings each one applies. */
11253
- presets: StylingPresetDescriptor[];
11254
- };
11255
11277
  /**
11256
11278
  * A named bundle of knob settings — TomTom's cartographic opinions, in code. Apply one with
11257
11279
  * {@link StylingModule.applyPreset}.
11258
11280
  *
11259
11281
  * @group Map Styling
11260
11282
  */
11261
- type StylingPresetDescriptor = {
11283
+ type StylingPreset = {
11262
11284
  id: StylingPresetId;
11263
11285
  name: string;
11264
11286
  /** One line on the use case the preset serves. */
@@ -11381,7 +11403,7 @@ type KnobDefinitionOf<KIND extends StylingKnobKind> = KnobDefinition & {
11381
11403
  /**
11382
11404
  * The styling knob catalogue: what the SDK can restyle on a TomTom standard style, and how.
11383
11405
  *
11384
- * Ids are public API — additive only. Ranges follow TomTom Map Maker's validated grammar (factors
11406
+ * Ids are public API — additive only. Ranges follow the validated grammar of TomTom's style editor (factors
11385
11407
  * 0.5–1.5 in 0.1 steps) so a value that looks right in the designer's tool looks right here.
11386
11408
  * @ignore
11387
11409
  */
@@ -11574,7 +11596,7 @@ declare const knobDefinitions: {
11574
11596
  readonly 'colors.labelOutline': KnobDefinitionOf<"color">;
11575
11597
  };
11576
11598
  /**
11577
- * The id of a styling knob — see {@link StylingModule.describe} for what each one does.
11599
+ * The id of a styling knob — see {@link stylingKnobCatalogue} for what each one does.
11578
11600
  *
11579
11601
  * @group Map Styling
11580
11602
  */
@@ -11585,6 +11607,14 @@ type StylingKnobId = keyof typeof knobDefinitions;
11585
11607
  * @group Map Styling
11586
11608
  */
11587
11609
  export declare const stylingKnobIds: StylingKnobId[];
11610
+ /**
11611
+ * Every styling knob with its kind, description, range or options and the styles it works on, in
11612
+ * catalogue order. Static data: a UI or a coding agent reads it with no map loaded, and
11613
+ * {@link StylingModule.get} gives the value in force on a live one.
11614
+ *
11615
+ * @group Map Styling
11616
+ */
11617
+ export declare const stylingKnobCatalogue: readonly StylingKnob[];
11588
11618
  /**
11589
11619
  * The id of a styling knob that holds a colour — every colour the styling module can name, and so
11590
11620
  * resolve against whichever style is loaded.
@@ -11725,15 +11755,15 @@ export type StylingEvents = CombinedEvents<MapGeoJSONFeature, StylingSettings, n
11725
11755
  * hand-editing MapLibre layers.
11726
11756
  *
11727
11757
  * Every adjustable thing is a **knob** with a stable id, a kind, a range and a default read from the
11728
- * loaded style. {@link describe} returns that catalogue as data, so a UI or an AI agent can build
11729
- * controls, validate values and diff state without knowing anything about the style's layers.
11758
+ * loaded style. The ids form the {@link StylingKnobId} union, and {@link stylingKnobCatalogue} lists
11759
+ * each one's kind, range and description as data, with no map needed to read it.
11730
11760
  *
11731
11761
  * @remarks
11732
11762
  * **Which styles a knob works on** is `appliesTo` in the catalogue. `any-style` knobs (sizes,
11733
11763
  * widths) wrap whatever the style already does — `text-size: E` becomes `["*", 1.3, E]` — so they
11734
11764
  * work on a custom style too. `tomtom-styles` knobs (toggles, colours) reach their layers through
11735
- * the TomTom styles this SDK version is verified against; on any other style they report
11736
- * `available: false`, warn once and do nothing rather than failing silently.
11765
+ * the TomTom styles this SDK version is verified against; on any other style setting one warns once
11766
+ * and does nothing, rather than failing silently.
11737
11767
  *
11738
11768
  * **Style changes.** Settings are re-applied after every `setStyle` that carries state over, on top of
11739
11769
  * whatever the other modules restored, and dropped on a clean switch (`resetState: true`).
@@ -11752,9 +11782,9 @@ export type StylingEvents = CombinedEvents<MapGeoJSONFeature, StylingSettings, n
11752
11782
  * styling.set('roads.exitNumbers', false);
11753
11783
  * styling.set('traffic.flow.slowColor', '#f59e0b');
11754
11784
  *
11755
- * // Everything a control panel or an agent needs, as data:
11756
- * for (const knob of styling.describe().knobs) {
11757
- * console.log(knob.id, knob.kind, knob.range, knob.current);
11785
+ * // The catalogue as data, and each knob's value in force:
11786
+ * for (const knob of stylingKnobCatalogue) {
11787
+ * console.log(knob.id, knob.kind, knob.range, styling.get(knob.id));
11758
11788
  * }
11759
11789
  *
11760
11790
  * // Serializable, diffable, re-applicable:
@@ -11776,6 +11806,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11776
11806
  private mapColorTargetsByKey;
11777
11807
  private mapColorTargetsByKnob;
11778
11808
  private mapColorAnchors;
11809
+ private landDerivedColors;
11779
11810
  private warned;
11780
11811
  private reindexed;
11781
11812
  private originalSpaceColor;
@@ -11828,24 +11859,9 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11828
11859
  get layers(): {
11829
11860
  query: (query: LayerQuery) => LayerSelection;
11830
11861
  };
11831
- /**
11832
- * The styling catalogue for the loaded style: every knob with its kind, range, default, current
11833
- * value and how many layers it reaches.
11834
- *
11835
- * @remarks
11836
- * Meant to be consumed as data — build a control panel from it, hand it to an agent, or diff two
11837
- * calls. Knob ids and the shape of the entries are public API and change additively only.
11838
- *
11839
- * @example
11840
- * ```typescript
11841
- * const { knobs } = styling.describe();
11842
- * const sliders = knobs.filter((knob) => knob.kind === 'factor' && knob.available);
11843
- * ```
11844
- */
11845
- describe(): StylingCatalogue;
11846
11862
  /**
11847
11863
  * Applies a preset: a named bundle of knob settings the SDK ships for a common intent
11848
- * (`data-viz`, `night-driving`, `minimal`, `globe`). See `describe().presets` for
11864
+ * (`data-viz`, `night-driving`, `minimal`, `globe`). See {@link stylingPresetCatalogue} for
11849
11865
  * what each one sets.
11850
11866
  *
11851
11867
  * @param id - The preset to apply.
@@ -11881,7 +11897,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11881
11897
  * Sets one knob. The value is validated against the knob's kind and range before anything is
11882
11898
  * touched, and applied to every layer the knob reaches.
11883
11899
  *
11884
- * @param id - The knob to set; see {@link describe} for the catalogue.
11900
+ * @param id - The knob to set; see {@link stylingKnobCatalogue} for the catalogue.
11885
11901
  * @param value - A number for `factor`/`number` knobs (within `range`), a boolean for `toggle`
11886
11902
  * knobs, a CSS colour string for `color` knobs.
11887
11903
  * @throws `RangeError` when the value is not valid for the knob; `Error` for an unknown id.
@@ -11907,14 +11923,16 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11907
11923
  */
11908
11924
  reset(id?: StylingKnobId): void;
11909
11925
  /**
11910
- * Recolours the whole base map with up to ten semantic colours in one call — Map Maker's
11911
- * Foundations palette, each listed with what it reaches under {@link MapColorName}. Partial
11912
- * objects are fine; colours not given stay as they are.
11926
+ * Recolours the whole base map with up to ten semantic colours in one call — the style
11927
+ * themes' Foundations palette, each listed with what it reaches under {@link MapColorName}. Partial
11928
+ * objects are fine; colours not given stay as they are, except on the mono styles, which derive
11929
+ * the other nine from `land` as their theme does: there the theme's own formulas re-derive them
11930
+ * from the `land` given.
11913
11931
  *
11914
11932
  * @remarks
11915
11933
  * Each colour re-derives every shade the style built from it — a trunk variant, an outline, a
11916
11934
  * tunnel — at the style's own HSL offset, so those relationships survive the recolour. The ten
11917
- * are also the `colors.*` knobs, so `describe()`, `reset` and settings persistence apply.
11935
+ * are also the `colors.*` knobs, so `get`, `reset` and settings persistence apply.
11918
11936
  *
11919
11937
  * Those offsets come off the loaded style, which makes a palette a recolour and not an
11920
11938
  * inversion: dark land over `standardLight` pushes the derived shades to the ends of their
@@ -11927,6 +11945,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11927
11945
  * ```typescript
11928
11946
  * styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });
11929
11947
  * styling.reset('colors.roadMajor'); // one colour back to the style
11948
+ * styling.setMapColors(deriveMapColors(['#0b2a3a', '#0fa8c8', '#f6efe3'])); // map-theme plugin assigns the roles
11930
11949
  * ```
11931
11950
  */
11932
11951
  setMapColors(colors: MapColors): void;
@@ -11959,6 +11978,9 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11959
11978
  private refreshLayer;
11960
11979
  private refreshSpace;
11961
11980
  private defaultSpaceColor;
11981
+ private refreshMapColor;
11982
+ private derivedMapColorOf;
11983
+ private mapColorsOf;
11962
11984
  private refreshMapColorProperty;
11963
11985
  private refreshProjection;
11964
11986
  private refreshSky;
@@ -11969,7 +11991,6 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
11969
11991
  private refreshScaledProperty;
11970
11992
  private refreshColor;
11971
11993
  private setProperty;
11972
- private describeKnob;
11973
11994
  private defaultOf;
11974
11995
  private mapLevelDefaultOf;
11975
11996
  private assertKnob;
@@ -12031,6 +12052,10 @@ type TerrainSourcesWithLayers = {
12031
12052
  * elevation data of the map style.
12032
12053
  *
12033
12054
  * @remarks
12055
+ * **What this module owns:** whether the hillshade is shown, and whether and how high the surface is raised.
12056
+ * Shading method, light direction, strength, zoom range and colours are `hillshade.*` {@link StylingModule} knobs.
12057
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
12058
+ *
12034
12059
  * - **Hillshade** shades slopes on the flat map, so the relief reads at any pitch.
12035
12060
  * - **Elevation** raises the map surface in 3D, which a pitched camera shows. Combined with the
12036
12061
  * hillshade, a slope stays readable where the camera flattens it.
@@ -12310,7 +12335,7 @@ type AreaAnalyticsMetricConfig = {
12310
12335
  * @example
12311
12336
  * ```typescript
12312
12337
  * // Move all layers below the lowest label
12313
- * const config: TrafficAreaAnalyticsConfig = {
12338
+ * const config: TrafficAreaAnalyticsModuleConfig = {
12314
12339
  * beforeLayerConfig: {
12315
12340
  * heatmap: 'lowestLabel',
12316
12341
  * hexgrid: { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
@@ -12319,7 +12344,7 @@ type AreaAnalyticsMetricConfig = {
12319
12344
  * };
12320
12345
  *
12321
12346
  * // Only reposition the heatmap layer
12322
- * const config: TrafficAreaAnalyticsConfig = {
12347
+ * const config: TrafficAreaAnalyticsModuleConfig = {
12323
12348
  * beforeLayerConfig: { heatmap: 'top' },
12324
12349
  * };
12325
12350
  * ```
@@ -12403,7 +12428,7 @@ declare const TRAFFIC_LIGHT_COLORS: {
12403
12428
  readonly bad: "#e03030";
12404
12429
  };
12405
12430
  /**
12406
- * Default values for all {@link TrafficAreaAnalyticsConfig} options.
12431
+ * Default values for all {@link TrafficAreaAnalyticsModuleConfig} options.
12407
12432
  *
12408
12433
  * Use these as a reference for what the module applies when a property is omitted,
12409
12434
  * or spread them as a base when constructing a config programmatically.
@@ -12411,13 +12436,13 @@ declare const TRAFFIC_LIGHT_COLORS: {
12411
12436
  * @group Traffic Area Analytics
12412
12437
  */
12413
12438
  declare const AREA_ANALYTICS_DEFAULTS: {
12414
- /** @see {@link TrafficAreaAnalyticsConfig.visible} */
12439
+ /** @see {@link TrafficAreaAnalyticsModuleConfig.visible} */
12415
12440
  visible: true;
12416
- /** @see {@link TrafficAreaAnalyticsConfig.displayMode} */
12441
+ /** @see {@link TrafficAreaAnalyticsModuleConfig.displayMode} */
12417
12442
  displayMode: "hexgrid-3d";
12418
- /** @see {@link TrafficAreaAnalyticsConfig.activeMetric} */
12443
+ /** @see {@link TrafficAreaAnalyticsModuleConfig.activeMetric} */
12419
12444
  activeMetric: "congestionLevel";
12420
- /** @see {@link TrafficAreaAnalyticsConfig.metricConfig} */
12445
+ /** @see {@link TrafficAreaAnalyticsModuleConfig.metricConfig} */
12421
12446
  metricConfig: {
12422
12447
  congestionLevel: {
12423
12448
  color: {
@@ -12542,7 +12567,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
12542
12567
  *
12543
12568
  * @example
12544
12569
  * ```typescript
12545
- * const config: TrafficAreaAnalyticsConfig = {
12570
+ * const config: TrafficAreaAnalyticsModuleConfig = {
12546
12571
  * displayMode: 'hexgrid-3d',
12547
12572
  * activeMetric: 'congestionLevel',
12548
12573
  * metricConfig: {
@@ -12567,7 +12592,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
12567
12592
  *
12568
12593
  * @group Traffic Area Analytics
12569
12594
  */
12570
- type TrafficAreaAnalyticsConfig = MapModuleCommonConfig & {
12595
+ type TrafficAreaAnalyticsModuleConfig = MapModuleCommonConfig & {
12571
12596
  /**
12572
12597
  * Controls the visibility of the area analytics layers.
12573
12598
  *
@@ -12674,7 +12699,7 @@ type AreaAnalyticsSourcesWithLayers = {
12674
12699
  *
12675
12700
  * @group Traffic Area Analytics
12676
12701
  */
12677
- export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
12702
+ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsModuleConfig> {
12678
12703
  private heatmapLayerSpec;
12679
12704
  private hexFillLayerSpec;
12680
12705
  private hexExtrusionLayerSpec;
@@ -12720,12 +12745,12 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
12720
12745
  * });
12721
12746
  * ```
12722
12747
  */
12723
- static create(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsConfig): Promise<TrafficAreaAnalyticsModule>;
12748
+ static create(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsModuleConfig): Promise<TrafficAreaAnalyticsModule>;
12724
12749
  private constructor();
12725
12750
  /** @ignore */
12726
- protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
12751
+ protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsModuleConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
12727
12752
  /** @ignore */
12728
- protected _applyConfig(config: TrafficAreaAnalyticsConfig | undefined): TrafficAreaAnalyticsConfig | undefined;
12753
+ protected _applyConfig(config: TrafficAreaAnalyticsModuleConfig | undefined): TrafficAreaAnalyticsModuleConfig | undefined;
12729
12754
  private moveLayersToSpecPositions;
12730
12755
  /** @ignore */
12731
12756
  protected discardShownData(): void;
@@ -12888,7 +12913,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
12888
12913
  * });
12889
12914
  * ```
12890
12915
  */
12891
- get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsConfig, TrafficAreaAnalytics>;
12916
+ get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsModuleConfig, TrafficAreaAnalytics>;
12892
12917
  private get mode();
12893
12918
  private get activeMetric();
12894
12919
  private get lightDark();
@@ -13021,7 +13046,7 @@ export type TrafficCommonFilter = {
13021
13046
  * @example
13022
13047
  * ```ts
13023
13048
  * // Hide minor local streets
13024
- * roadSubCategories: { show: 'all_except', values: ['living_street'] }
13049
+ * roadSubCategories: { show: 'all-except', values: ['living_street'] }
13025
13050
  * ```
13026
13051
  */
13027
13052
  roadSubCategories?: ValuesFilter<RoadSubCategory>;
@@ -13093,7 +13118,7 @@ export type TrafficFlowFilters = {
13093
13118
  *
13094
13119
  * @group Traffic Flow
13095
13120
  */
13096
- export type FlowConfig = MapModuleCommonConfig & {
13121
+ export type TrafficFlowModuleConfig = MapModuleCommonConfig & {
13097
13122
  /**
13098
13123
  * Controls the visibility of the traffic flow layers.
13099
13124
  *
@@ -13115,6 +13140,12 @@ export type FlowConfig = MapModuleCommonConfig & {
13115
13140
  * Defines the structure of a traffic flow feature, which extends the basic GeoJSON feature
13116
13141
  * with properties extracted from the traffic flow vector tiles.
13117
13142
  *
13143
+ * @remarks
13144
+ * `absoluteSpeed`, `partOfTwoWayRoad` and `openlr` stay `undefined` with the standard styles, which do
13145
+ * not request their tile tags; a custom style whose flow source asks for them populates them.
13146
+ * No flow tile carries free-flow speed, travel time, delay or confidence: for historical speed and
13147
+ * congestion over an area, use the Traffic Area Analytics service.
13148
+ *
13118
13149
  * @group Traffic Flow
13119
13150
  */
13120
13151
  export type TrafficFlowModuleFeature = Feature<LineString, {
@@ -13170,6 +13201,10 @@ type TrafficFlowSourcesWithLayers = {
13170
13201
  * traffic speed conditions using color-coded road segments.
13171
13202
  *
13172
13203
  * @remarks
13204
+ * **What this module owns:** whether the style's traffic-flow layers are shown, and for which roads.
13205
+ * Each flow level's colour and the line width are `traffic.flow.*` knobs on {@link StylingModule}.
13206
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
13207
+ *
13173
13208
  * **Features:**
13174
13209
  * - Toggle traffic flow visibility on/off
13175
13210
  * - Filter by road categories and types
@@ -13215,7 +13250,7 @@ type TrafficFlowSourcesWithLayers = {
13215
13250
  * trafficFlow.filter({
13216
13251
  * any: [{
13217
13252
  * roadCategories: {
13218
- * show: 'all_except',
13253
+ * show: 'all-except',
13219
13254
  * values: ['street']
13220
13255
  * }
13221
13256
  * }]
@@ -13237,7 +13272,7 @@ type TrafficFlowSourcesWithLayers = {
13237
13272
  *
13238
13273
  * @group Traffic Flow
13239
13274
  */
13240
- export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<TrafficFlowSourcesWithLayers, FlowConfig> {
13275
+ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<TrafficFlowSourcesWithLayers, TrafficFlowModuleConfig> {
13241
13276
  /**
13242
13277
  * Retrieves a TrafficFlowModule instance for the given map.
13243
13278
  *
@@ -13285,7 +13320,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
13285
13320
  * provides, under fixed global IDs. Every instance is another handle on that same shared state,
13286
13321
  * so visibility and filters applied through one are visible through all of them.
13287
13322
  */
13288
- static get(map: TomTomMap, config?: FlowConfig): Promise<TrafficFlowModule>;
13323
+ static get(map: TomTomMap, config?: TrafficFlowModuleConfig): Promise<TrafficFlowModule>;
13289
13324
  private constructor();
13290
13325
  /**
13291
13326
  * @ignore
@@ -13296,7 +13331,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
13296
13331
  /**
13297
13332
  * @ignore
13298
13333
  */
13299
- protected _applyConfig(config: FlowConfig | undefined): FlowConfig | undefined;
13334
+ protected _applyConfig(config: TrafficFlowModuleConfig | undefined): TrafficFlowModuleConfig | undefined;
13300
13335
  private getLayers;
13301
13336
  /**
13302
13337
  * Applies filters to traffic flow display.
@@ -13340,7 +13375,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
13340
13375
  * trafficFlow.filter({
13341
13376
  * any: [{
13342
13377
  * roadCategories: {
13343
- * show: 'all_except',
13378
+ * show: 'all-except',
13344
13379
  * values: ['street']
13345
13380
  * }
13346
13381
  * }]
@@ -13393,16 +13428,9 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
13393
13428
  * @returns An object containing visible traffic flow features.
13394
13429
  *
13395
13430
  * @remarks
13396
- * Returns all traffic flow features currently rendered in the visible map area.
13397
- * These represent road segments with real-time traffic speed information.
13398
- *
13399
- * **Feature Properties:**
13400
- * Properties depend on the traffic flow vector tile schema and may include:
13401
- * - Current speed
13402
- * - Free flow speed
13403
- * - Road category
13404
- * - Congestion level
13405
- * - Road closure status
13431
+ * The only way to read live flow values: Orbis traffic flow is vector tiles, with no service for a
13432
+ * road, a point or an area. Results cover the current viewport and zoom, and a segment crossing a
13433
+ * tile boundary appears once per tile. See {@link TrafficFlowModuleFeature} for what each carries.
13406
13434
  *
13407
13435
  * @example
13408
13436
  * ```typescript
@@ -13418,7 +13446,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
13418
13446
  * ```typescript
13419
13447
  * const shown = trafficFlow.getShown();
13420
13448
  * const congested = shown.trafficFlow.filter(
13421
- * segment => segment.properties.speed < segment.properties.freeFlowSpeed * 0.5
13449
+ * segment => segment.properties.relativeSpeed < 0.5
13422
13450
  * );
13423
13451
  * console.log(`Congested segments: ${congested.length}`);
13424
13452
  * ```
@@ -13426,7 +13454,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
13426
13454
  getShown(): {
13427
13455
  trafficFlow: TrafficFlowModuleFeature[];
13428
13456
  };
13429
- get events(): CombinedEvents<TrafficFlowModuleFeature, FlowConfig, never>;
13457
+ get events(): CombinedEvents<TrafficFlowModuleFeature, TrafficFlowModuleConfig, never>;
13430
13458
  }
13431
13459
  //#endregion
13432
13460
  //#region src/traffic/types/trafficIncidentOverlayConfig.d.ts
@@ -13454,7 +13482,7 @@ type IncidentFocusStyle = {
13454
13482
  *
13455
13483
  * @group Traffic
13456
13484
  */
13457
- type TrafficIncidentOverlayConfig = MapModuleCommonConfig & {
13485
+ type TrafficIncidentOverlayModuleConfig = MapModuleCommonConfig & {
13458
13486
  /**
13459
13487
  * Initial visibility of all incident layers. Defaults to `true`.
13460
13488
  * `show()` never flips this flag — if `false`, the module loads data but
@@ -13580,7 +13608,7 @@ type Sources = {
13580
13608
  *
13581
13609
  * @group Traffic
13582
13610
  */
13583
- export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentOverlayConfig> {
13611
+ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentOverlayModuleConfig> {
13584
13612
  private lastResult;
13585
13613
  private lastFeatureIds;
13586
13614
  private lastFocusIds;
@@ -13596,12 +13624,12 @@ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapMo
13596
13624
  * @param config The module optional configuration.
13597
13625
  * @returns {Promise} Returns a promise with a new instance of this module.
13598
13626
  */
13599
- static create(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayConfig): Promise<TrafficIncidentOverlayModule>;
13627
+ static create(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayModuleConfig): Promise<TrafficIncidentOverlayModule>;
13600
13628
  private constructor();
13601
13629
  /** @ignore */
13602
- protected _initSourcesWithLayers(config?: TrafficIncidentOverlayConfig, _restore?: boolean): Sources;
13630
+ protected _initSourcesWithLayers(config?: TrafficIncidentOverlayModuleConfig, _restore?: boolean): Sources;
13603
13631
  /** @ignore */
13604
- protected _applyConfig(config: TrafficIncidentOverlayConfig | undefined): TrafficIncidentOverlayConfig | undefined;
13632
+ protected _applyConfig(config: TrafficIncidentOverlayModuleConfig | undefined): TrafficIncidentOverlayModuleConfig | undefined;
13605
13633
  private applyBeforeLayer;
13606
13634
  /** @ignore */
13607
13635
  protected discardShownData(): void;
@@ -13639,7 +13667,7 @@ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapMo
13639
13667
  getShown(): {
13640
13668
  incidents: TrafficIncidentDetails;
13641
13669
  };
13642
- get events(): CombinedEvents<TrafficIncident, TrafficIncidentOverlayConfig, TrafficIncidentDetails>;
13670
+ get events(): CombinedEvents<TrafficIncident, TrafficIncidentOverlayModuleConfig, TrafficIncidentDetails>;
13643
13671
  /**
13644
13672
  * Mark a subset of currently-rendered incidents as "focused" via MapLibre
13645
13673
  * feature-state. `null` clears the state. Paint expressions in
@@ -13737,7 +13765,7 @@ export type TrafficIncidentsFilter = TrafficCommonFilter & {
13737
13765
  * magnitudes: { show: 'only', values: ['moderate', 'major'] }
13738
13766
  *
13739
13767
  * // Hide minor incidents
13740
- * magnitudes: { show: 'all_except', values: ['minor'] }
13768
+ * magnitudes: { show: 'all-except', values: ['minor'] }
13741
13769
  * ```
13742
13770
  */
13743
13771
  magnitudes?: ValuesFilter<DelayMagnitude>;
@@ -13814,7 +13842,7 @@ export type IncidentsCommonConfig = {
13814
13842
  *
13815
13843
  * @group Traffic Incidents
13816
13844
  */
13817
- export type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
13845
+ export type TrafficIncidentsModuleConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
13818
13846
  /**
13819
13847
  * Configuration specific to incident icon display.
13820
13848
  *
@@ -13882,6 +13910,10 @@ type TrafficIncidentsSourcesWithLayers = {
13882
13910
  * events like accidents, road closures, construction, and hazards.
13883
13911
  *
13884
13912
  * @remarks
13913
+ * **What this module owns:** whether the style's incident layers are shown, and which incidents.
13914
+ * Each magnitude's colour and the line width are `traffic.incidents.*` knobs on {@link StylingModule}.
13915
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
13916
+ *
13885
13917
  * **Features:**
13886
13918
  * - Toggle incidents visibility on/off
13887
13919
  * - Separate control for incident icons
@@ -13934,7 +13966,7 @@ type TrafficIncidentsSourcesWithLayers = {
13934
13966
  * trafficIncidentsModule.filter({
13935
13967
  * any: [{
13936
13968
  * incidentCategories: {
13937
- * show: 'all_except',
13969
+ * show: 'all-except',
13938
13970
  * values: ['roadworks']
13939
13971
  * }
13940
13972
  * }]
@@ -13990,7 +14022,7 @@ type TrafficIncidentsSourcesWithLayers = {
13990
14022
  *
13991
14023
  * @group Traffic Incidents
13992
14024
  */
13993
- export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<TrafficIncidentsSourcesWithLayers, IncidentsConfig> {
14025
+ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<TrafficIncidentsSourcesWithLayers, TrafficIncidentsModuleConfig> {
13994
14026
  /**
13995
14027
  * Retrieves a TrafficIncidentsModule instance for the given map.
13996
14028
  *
@@ -14038,7 +14070,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
14038
14070
  * provides, under fixed global IDs. Every instance is another handle on that same shared state,
14039
14071
  * so visibility and filters applied through one are visible through all of them.
14040
14072
  */
14041
- static get(map: TomTomMap, config?: IncidentsConfig): Promise<TrafficIncidentsModule>;
14073
+ static get(map: TomTomMap, config?: TrafficIncidentsModuleConfig): Promise<TrafficIncidentsModule>;
14042
14074
  private constructor();
14043
14075
  /**
14044
14076
  * @ignore
@@ -14049,7 +14081,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
14049
14081
  /**
14050
14082
  * @ignore
14051
14083
  */
14052
- protected _applyConfig(config: IncidentsConfig | undefined): IncidentsConfig | undefined;
14084
+ protected _applyConfig(config: TrafficIncidentsModuleConfig | undefined): TrafficIncidentsModuleConfig | undefined;
14053
14085
  /**
14054
14086
  * Applies filters to traffic incidents display.
14055
14087
  *
@@ -14231,7 +14263,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
14231
14263
  getShown(): {
14232
14264
  trafficIncidents: TrafficIncidentsModuleFeature[];
14233
14265
  };
14234
- get events(): CombinedEvents<TrafficIncidentsModuleFeature, IncidentsConfig, never>;
14266
+ get events(): CombinedEvents<TrafficIncidentsModuleFeature, TrafficIncidentsModuleConfig, never>;
14235
14267
  }
14236
14268
  //#endregion
14237
14269
  //#region src/utils/colorUtils.d.ts
@@ -14241,12 +14273,34 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
14241
14273
  */
14242
14274
  type RGBAColor = [number, number, number, number];
14243
14275
  /**
14244
- * Parses any CSS colour a map style writes — `#rgb`, `#rrggbb(aa)`, `rgb()`/`rgba()` in numbers or
14245
- * percentages, `hsl()`/`hsla()`, `transparent` and the named colours — or `undefined` for a string
14246
- * that is not one.
14276
+ * {@link parseColor} as an {@link RGBAColor} tuple.
14247
14277
  * @ignore
14248
14278
  */
14249
14279
  export declare const parseCssColor: (cssColor: string) => RGBAColor | undefined;
14280
+ /**
14281
+ * A colour in HSL: hue in degrees (none for a grey), saturation, lightness and alpha 0–1 — the shape
14282
+ * of culori's `Hsl`, so culori's functions take it.
14283
+ * @ignore
14284
+ */
14285
+ type HslColor = {
14286
+ mode: 'hsl';
14287
+ h?: number;
14288
+ s: number;
14289
+ l: number;
14290
+ alpha?: number;
14291
+ };
14292
+ /**
14293
+ * The HSL of a CSS colour, or `undefined` when it cannot be parsed. Read through sRGB, so an
14294
+ * `hsl()` literal comes back canonical — white has no saturation, a grey no hue.
14295
+ * @ignore
14296
+ */
14297
+ export declare const toHsl: (cssColor: string) => HslColor | undefined;
14298
+ /**
14299
+ * Formats an HSL colour as a CSS `hsl()`/`hsla()` string, rounded to what the map styles themselves
14300
+ * use: whole degrees and percents.
14301
+ * @ignore
14302
+ */
14303
+ export declare const formatStyleHsl: (hsl: Omit<HslColor, "mode">) => string;
14250
14304
  //#endregion
14251
14305
  //#region src/utils/types/paddedBounds.d.ts
14252
14306
  /**
@@ -14328,4 +14382,4 @@ export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions)
14328
14382
  */
14329
14383
  export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
14330
14384
  //#endregion
14331
- export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventType, ExtraFeatureProp, FeaturePropValue, FilterShowMode, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, IncidentFocusStyle, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RGBAColor, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingCatalogue, StylingColorKnobId, StylingKnobAppliesTo, StylingKnobDescriptor, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPresetDescriptor, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };
14385
+ export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventHandlerHoverConfig, EventState, EventType, ExtraFeatureProp, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, HslColor, IncidentFocusStyle, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RGBAColor, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingColorKnobId, StylingKnob, StylingKnobAppliesTo, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPreset, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsModuleConfig, TrafficIncidentOverlayModuleConfig, UserEventHandler, WaypointsConfig };