@tomtom-org/maps-sdk 0.47.5 → 0.47.7

package/map/dist/index.d.ts

@@ -51,6 +51,8 @@ import { Routes as Routes_2 } from '@tomtom-org/maps-sdk/core';
 import { SectionProps } from '@tomtom-org/maps-sdk/core';
 import { Source } from 'maplibre-gl';
 import { SourceSpecification } from 'maplibre-gl';
+import { StyleImageInterface } from 'maplibre-gl';
+import { StyleImageMetadata } from 'maplibre-gl';
 import { StyleSpecification } from 'maplibre-gl';
 import { SymbolLayerSpecification } from 'maplibre-gl';
 import { TrafficAreaAnalytics } from '@tomtom-org/maps-sdk/core';
@@ -181,6 +183,20 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
      * @ignore
      */
     protected readonly configChangeHandlers: ((config: CFG | undefined) => void)[];
+    /**
+     * Monotonically increasing index unique to this instance within its concrete module
+     * class. Auto-assigned in the constructor based on `new.target`, so each subclass
+     * has its own counter without per-subclass boilerplate. Use as a suffix on
+     * auto-generated source and layer IDs to keep them stable across style changes and
+     * unique across module instances.
+     * @ignore
+     */
+    protected readonly instanceIndex: number;
+    /**
+     * Per-concrete-class instance counter. WeakMap-keyed so unloaded classes can be GC'd.
+     * @ignore
+     */
+    private static readonly instanceCounters;
     /**
      * Indicates that this module is currently adding its sources and layers to the map, so during this time it might not function properly.
      * @see waitUntilModuleReady
@@ -1122,7 +1138,7 @@ export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers
      * @ignore
      */
     protected _initSourcesWithLayers(config: BaseMapModuleInitConfig | undefined): {
-        vectorTiles: StyleSourceWithLayers<SourceSpecification, Source>;
+        vectorTiles: StyleSourceWithLayers< SourceSpecification, Source>;
     };
     /**
      * @ignore
@@ -1227,7 +1243,7 @@ export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers
      * unsub(); // remove by returned function
      * ```
      */
-    get events(): CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfig, never>;
+    get events(): CombinedEvents< MapGeoJSONFeature, BaseMapModuleConfig, never>;
 }
 
 /**
@@ -1941,6 +1957,338 @@ declare type ConnectionFeatureProps = {
  */
 export declare type CSSCursor = 'alias' | 'all-scroll' | 'auto' | 'cell' | 'context-menu' | 'col-resize' | 'copy' | 'crosshair' | 'default' | 'e-resize' | 'ew-resize' | 'grab' | 'grabbing' | 'help' | 'move' | 'n-resize' | 'ne-resize' | 'nesw-resize' | 'ns-resize' | 'nw-resize' | 'nwse-resize' | 'no-drop' | 'none' | 'not-allowed' | 'pointer' | 'progress' | 'row-resize' | 's-resize' | 'se-resize' | 'sw-resize' | 'text' | 'vertical-text' | 'w-resize' | 'wait' | 'zoom-in' | 'zoom-out';
 
+/**
+ * Per-source {@link CombinedEvents} surface keyed by the source name supplied in
+ * {@link CustomGeoJSONModuleConfig.sources}.
+ *
+ * @group Custom
+ */
+export declare type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = {
+    [K in keyof TSources]: CombinedEvents<MapGeoJSONFeature, CustomGeoJSONModuleConfig<TSources>, TSources[K]>;
+};
+
+/**
+ * Any image payload accepted by MapLibre's `map.addImage`. Mirrors the parameter type
+ * of that method.
+ *
+ * @group Custom
+ */
+export declare type CustomGeoJSONImageData = HTMLImageElement | ImageBitmap | ImageData | StyleImageInterface | {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+};
+
+/**
+ * Specification for a single custom image registered on the map by a
+ * {@link CustomGeoJSONModule}. The module re-registers every image automatically after
+ * every style change, so symbol layers in {@link CustomGeoJSONSourceSpec.layers} can
+ * reference an image by ID and survive `setStyle` calls without extra wiring.
+ *
+ * @group Custom
+ */
+export declare type CustomGeoJSONImageSpec = {
+    /**
+     * The image data, in any format accepted by MapLibre's `addImage`. Asynchronous
+     * sources (URLs, SVG strings) are not supported here — pre-load them and pass an
+     * `HTMLImageElement` (or `ImageBitmap`/`ImageData`) instead.
+     */
+    image: CustomGeoJSONImageData;
+    /**
+     * MapLibre image metadata: `pixelRatio`, `sdf`, `stretchX`, `stretchY`, `content`.
+     * Forwarded verbatim to `addImage`.
+     */
+    options?: Partial<StyleImageMetadata>;
+};
+
+/**
+ * Specification for a single custom layer attached to a {@link CustomGeoJSONSourceSpec}.
+ *
+ * Equivalent to a MapLibre layer specification (one of `circle`, `line`, `fill`,
+ * `symbol`, `heatmap`, …) with `source` and `id` removed, and an optional `beforeID`
+ * for ordering. The variant is preserved by `type`, so variant-specific properties
+ * (`filter`, `layout`, `paint`, …) keep their narrow types.
+ *
+ * `id` is auto-generated as `${sourceID}-layer-${layerIndex}` when omitted. Provide
+ * an explicit ID when you want to refer to the layer from outside the module
+ * (e.g. to remove it via {@link applyConfig}), or when the layer set is expected to
+ * change at runtime and you want a stable identity that is independent of array order.
+ *
+ * `beforeID` is the ID of an existing map layer the new layer should be inserted
+ * before — see MapLibre's `addLayer`.
+ *
+ * @group Custom
+ */
+export declare type CustomGeoJSONLayerSpec = DistributiveOmit<LayerSpecWithSource, 'source' | 'id'> & {
+    id?: string;
+    beforeID?: string;
+};
+
+/**
+ * Module for displaying customer-owned GeoJSON data with TomTom SDK support.
+ *
+ * Wraps one or more MapLibre GeoJSON sources together with caller-supplied layer specs,
+ * and adds the usual TomTom SDK lifecycle behaviour on top: style-change restoration,
+ * `config-change` / `shown-features` events, and per-source user interaction events
+ * (`click`, `hover`, `long-hover`, `contextmenu`).
+ *
+ * Unlike opinionated modules such as {@link PlacesModule} or {@link GeometriesModule},
+ * this module makes no assumptions about how data is rendered — the caller passes raw
+ * MapLibre layer specs (`circle`, `heatmap`, `fill`, `line`, `symbol`, …).
+ *
+ * @typeParam TSources - A record mapping source names to the {@link FeatureCollection}
+ * type each source carries. Pass this generic when you want type-safe `show` /
+ * `getShown` per source.
+ *
+ * @example
+ * Single source, default generic:
+ * ```typescript
+ * const module = await CustomGeoJSONModule.get(map, {
+ *     sources: {
+ *         points: {
+ *             layers: [{ type: 'circle', paint: { 'circle-radius': 4, 'circle-color': '#0a3653' } }],
+ *         },
+ *     },
+ * });
+ *
+ * await module.show(myFeatureCollection, 'points');
+ * module.events.points.on('click', (feature, lngLat) => console.log(feature, lngLat));
+ * ```
+ *
+ * @example
+ * Multiple sources with typed payloads:
+ * ```typescript
+ * type Sources = {
+ *     heatmap: FeatureCollection<Point>;
+ *     buildings: FeatureCollection<Polygon, { name: string }>;
+ * };
+ *
+ * const module = await CustomGeoJSONModule.get<Sources>(map, {
+ *     sources: {
+ *         heatmap: { layers: [{ type: 'heatmap', paint: { 'heatmap-radius': 12 } }] },
+ *         buildings: { layers: [{ type: 'fill', paint: { 'fill-color': '#5a5' } }] },
+ *     },
+ * });
+ *
+ * await module.show(heatmapData, 'heatmap');
+ * await module.show(buildingData, 'buildings');
+ * ```
+ *
+ * @example
+ * Same data, multiple renderings — call `show` once without a source name:
+ * ```typescript
+ * type Buildings = FeatureCollection<Point, { Name: string }>;
+ *
+ * const module = await CustomGeoJSONModule.get<{ heatmap: Buildings; markers: Buildings }>(map, {
+ *     sources: {
+ *         heatmap: { layers: heatmapLayers },
+ *         markers: { layers: markerLayers },
+ *     },
+ * });
+ *
+ * await module.show(buildingData); // applied to both sources
+ * ```
+ *
+ * @group Custom
+ */
+export declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> extends AbstractMapModule<CustomGeoJSONSourcesWithLayers<TSources>, CustomGeoJSONModuleConfig<TSources>> {
+    private resolvedSourceIDs;
+    private resolvedLayerSpecs;
+    private lastShown;
+    private shownFeaturesHandlersBySource;
+    /**
+     * Creates a new {@link CustomGeoJSONModule} once the map is ready.
+     *
+     * @param tomtomMap The TomTomMap instance.
+     * @param config Module configuration. `sources` is required and must contain at
+     * least one entry; each entry must have at least one layer.
+     */
+    static get<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>>(tomtomMap: TomTomMap, config: CustomGeoJSONModuleConfig<TSources>): Promise<CustomGeoJSONModule<TSources>>;
+    private constructor();
+    /**
+     * @ignore
+     */
+    protected _initSourcesWithLayers(config: CustomGeoJSONModuleConfig<TSources> | undefined, restore?: boolean): CustomGeoJSONSourcesWithLayers<TSources>;
+    private registerImages;
+    private resolveIDs;
+    /**
+     * @ignore
+     */
+    protected _applyConfig(config: CustomGeoJSONModuleConfig<TSources> | undefined): CustomGeoJSONModuleConfig<TSources> | undefined;
+    private updateLayersForExistingSources;
+    private applyVisibility;
+    /**
+     * @ignore
+     */
+    protected restoreDataAndConfigImpl(): void;
+    /**
+     * Displays the given GeoJSON data on the named source — or on every source when
+     * no name is supplied.
+     *
+     * Replaces any previously shown data. Layer visibility is set automatically based
+     * on whether the feature collection is non-empty.
+     *
+     * @param data The GeoJSON feature collection to display.
+     * @param sourceName The source name (must match a key from
+     * {@link CustomGeoJSONModuleConfig.sources}). When omitted, `data` is shown on
+     * every source — best used when every source shares the same `FeatureCollection`
+     * shape.
+     */
+    show<K extends keyof TSources>(data: TSources[K], sourceName?: K): Promise<void>;
+    private showOnSource;
+    /**
+     * Clears data from the given source — or from all sources when no name is supplied.
+     */
+    clear(sourceName?: keyof TSources): Promise<void>;
+    /**
+     * Returns the feature collection currently shown on each source.
+     *
+     * Sources that have never been shown (or have been cleared) return the empty
+     * feature collection that `GeoJSONSourceWithLayers` keeps as initial state.
+     */
+    getShown(): {
+        [K in keyof TSources]: TSources[K];
+    };
+    /**
+     * Toggles visibility of every layer across every source.
+     *
+     * @remarks
+     * Calling {@link show} on a source after `setVisible(false)` will re-reveal that
+     * source's layers via `GeoJSONSourceWithLayers`' automatic visibility behaviour.
+     * To keep a source hidden, call `setVisible(false)` after the next `show`.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Per-source events surface.
+     *
+     * Each key on the returned object is one of the source names declared in
+     * {@link CustomGeoJSONModuleConfig.sources}. Each value is a {@link CombinedEvents}
+     * instance covering both user interactions (`click`, `hover`, `long-hover`,
+     * `contextmenu`) and module lifecycle events (`config-change`, `shown-features`).
+     *
+     * `config-change` handlers are module-wide (the same handler array is shared
+     * across every source's `CombinedEvents`). `shown-features` handlers fire only for
+     * their own source.
+     *
+     * @example
+     * ```typescript
+     * module.events.buildings.on('click', (feature, lngLat) => { ... });
+     * module.events.heatmap.on('shown-features', (data) => { ... });
+     * module.events.buildings.on('config-change', (config) => { ... });
+     * ```
+     */
+    get events(): CustomGeoJSONEvents<TSources>;
+}
+
+/**
+ * Configuration for the {@link CustomGeoJSONModule}.
+ *
+ * @typeParam TSources - A record describing each source name and the
+ * {@link FeatureCollection} type it carries. When omitted, every source defaults to
+ * `FeatureCollection`.
+ *
+ * @example
+ * ```typescript
+ * type MySources = {
+ *     buildings: FeatureCollection<Point, { name: string }>;
+ *     parks: FeatureCollection<Polygon>;
+ * };
+ *
+ * const config: CustomGeoJSONModuleConfig<MySources> = {
+ *     sources: {
+ *         buildings: { layers: [{ type: 'circle', paint: { 'circle-radius': 4 } }] },
+ *         parks: { layers: [{ type: 'fill', paint: { 'fill-color': '#5a5' } }] },
+ *     },
+ * };
+ * ```
+ *
+ * @group Custom
+ */
+export declare type CustomGeoJSONModuleConfig<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> = MapModuleCommonConfig & {
+    /**
+     * The sources, keyed by an arbitrary user-defined name, that this module manages.
+     *
+     * @remarks
+     * The set of source names is fixed at module creation time. Calling
+     * {@link applyConfig} with new source names or omitting existing ones is **not**
+     * supported — only the layer specs and visibility of existing sources can be
+     * updated at runtime.
+     */
+    sources: {
+        [K in keyof TSources]: CustomGeoJSONSourceSpec;
+    };
+    /**
+     * Custom images to register on the map by ID. The module adds each image during
+     * setup, before any source or layer is created, and re-adds every image after every
+     * style change — so symbol layers referencing an image via `icon-image: '<id>'`
+     * survive `setStyle` calls automatically.
+     *
+     * @remarks
+     * - Existing images on the map are not overwritten — the module skips IDs for
+     *   which `map.hasImage(id)` is already `true`.
+     * - Only synchronous MapLibre image payloads are supported. URLs and raw SVG
+     *   strings must be loaded by the caller before being passed in.
+     * - `applyConfig` re-runs image registration **additively**: new IDs are added,
+     *   already-present IDs are skipped, and removing an entry from `images` does
+     *   not unregister it from the map (other layers may still reference it).
+     *
+     * @example
+     * ```typescript
+     * const config: CustomGeoJSONModuleConfig = {
+     *     sources: {
+     *         markers: { layers: [{ type: 'symbol', layout: { 'icon-image': 'my-marker' } }] },
+     *     },
+     *     images: {
+     *         'my-marker': { image: myImageBitmap, options: { pixelRatio: 2 } },
+     *     },
+     * };
+     * ```
+     */
+    images?: Record<string, CustomGeoJSONImageSpec>;
+    /**
+     * Initial visibility for all layers across all sources. Defaults to `true`.
+     *
+     * @remarks
+     * After `show(name, data)` is called for a source, layer visibility follows the
+     * data state (visible iff the feature collection is non-empty). Use
+     * {@link CustomGeoJSONModule.setVisible} to override that automatic behaviour at
+     * runtime.
+     */
+    visible?: boolean;
+};
+
+/**
+ * Configuration for one logical source managed by a {@link CustomGeoJSONModule}.
+ *
+ * Each entry corresponds to a single MapLibre GeoJSON source plus its associated layers.
+ *
+ * @group Custom
+ */
+export declare type CustomGeoJSONSourceSpec = {
+    /**
+     * Optional MapLibre source ID. Auto-generated as
+     * `custom-geojson-${instanceIndex}-${sourceName}` when absent.
+     */
+    sourceID?: string;
+    /**
+     * The layers that render this source. At least one layer is required for the source
+     * to be visible on the map.
+     */
+    layers: CustomGeoJSONLayerSpec[];
+    /**
+     * MapLibre cluster options, forwarded verbatim to the underlying GeoJSON source.
+     *
+     * @remarks
+     * Cluster options are applied at source creation time and cannot be changed via
+     * {@link applyConfig}. To change clustering, recreate the module.
+     */
+    cluster?: GeoJSONSourceClusterOptions;
+};
+
+declare type CustomGeoJSONSourcesWithLayers<TSources extends Record<string, FeatureCollection>> = {
+    [K in keyof TSources]: GeoJSONSourceWithLayers<TSources[K]>;
+};
+
 /**
  * Basic structure to define custom map icons, which end up in the map sprite.
  *
@@ -2655,6 +3003,8 @@ declare type DisplayTrafficSectionProps = DisplaySectionProps & TrafficSectionPr
     title?: string;
 };
 
+declare type DistributiveOmit<T, K extends string> = T extends unknown ? Omit<T, K> : never;
+
 /**
  * Configuration for EV charging station availability display.
  *
@@ -3129,7 +3479,6 @@ export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = Featu
  * @group Geometries
  */
 export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig> {
-    private static lastInstanceIndex;
     private titleLayerSpecs;
     private geometryFillLayerSpecs;
     private geometryOutlineLayerSpecs;
@@ -3421,7 +3770,7 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
      * });
      * ```
      */
-    get events(): CombinedEvents<MapGeoJSONFeature, GeometriesModuleConfig, PolygonFeatures>;
+    get events(): CombinedEvents< MapGeoJSONFeature, GeometriesModuleConfig, PolygonFeatures>;
 }
 
 /**
@@ -4116,7 +4465,7 @@ export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesW
      * @ignore
      */
     protected _initSourcesWithLayers(): {
-        hillshade: StyleSourceWithLayers<SourceSpecification, Source>;
+        hillshade: StyleSourceWithLayers< SourceSpecification, Source>;
     };
     /**
      * @ignore
@@ -4170,7 +4519,7 @@ export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesW
      * unsub();
      * ```
      */
-    get events(): CombinedEvents<MapGeoJSONFeature, HillshadeModuleConfig, never>;
+    get events(): CombinedEvents< MapGeoJSONFeature, HillshadeModuleConfig, never>;
 }
 
 /**
@@ -5398,7 +5747,6 @@ export declare type PlaceLayersConfig = {
 } & HasAdditionalLayersConfig;
 
 export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
-    private static lastInstanceIndex;
     private layerSpecs;
     private connectionLayerSpecs;
     private currentClusterMode;
@@ -5406,12 +5754,6 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
     private unclusteredSourceID;
     private connectionSourceID;
     private layerIDPrefix;
-    /**
-     * The index of this instance, to generate unique source and layer IDs.
-     * * Starts with 0 and each instance increments it by one.
-     * @private
-     */
-    private instanceIndex;
     private defaultPlaceIconID;
     private shownConnections;
     private readonly shownFeaturesHandlers;
@@ -6302,7 +6644,7 @@ export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers,
      * @ignore
      */
     protected _initSourcesWithLayers(): {
-        poi: StyleSourceWithLayers<SourceSpecification, Source>;
+        poi: StyleSourceWithLayers< SourceSpecification, Source>;
     };
     /**
      * @ignore
@@ -7370,15 +7712,8 @@ export declare type RouteWidth = 's' | 'm' | 'l';
  * @group Routing
  */
 export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers, RoutingModuleConfig> {
-    private static lastInstanceIndex;
     private layersSpecs;
     private layerIDPrefix;
-    /**
-     * The index of this instance, to generate unique source and layer IDs.
-     * * Starts with 0 and each instance increments it by one.
-     * @private
-     */
-    private instanceIndex;
     private readonly shownFeaturesHandlers;
     /**
      * Make sure the map is ready before create an instance of the module and any other interaction with the map
@@ -9136,7 +9471,6 @@ export declare type TrafficAreaAnalyticsConfig = MapModuleCommonConfig & {
  * @group Traffic Area Analytics
  */
 export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
-    private static lastInstanceIndex;
     private heatmapLayerSpec;
     private hexFillLayerSpec;
     private hexExtrusionLayerSpec;
@@ -9181,7 +9515,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAn
     static get(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsConfig): Promise<TrafficAreaAnalyticsModule>;
     private constructor();
     /** @ignore */
-    protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, restore?: boolean): AreaAnalyticsSourcesWithLayers;
+    protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
     /** @ignore */
     protected _applyConfig(config: TrafficAreaAnalyticsConfig | undefined): TrafficAreaAnalyticsConfig | undefined;
     /** @ignore */
@@ -9576,7 +9910,7 @@ export declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSour
      * @ignore
      */
     protected _initSourcesWithLayers(): {
-        trafficFlow: StyleSourceWithLayers<SourceSpecification, Source>;
+        trafficFlow: StyleSourceWithLayers< SourceSpecification, Source>;
     };
     /**
      * @ignore
@@ -9893,8 +10227,6 @@ export declare type TrafficIncidentOverlayConfig = MapModuleCommonConfig & {
  * @group Traffic
  */
 export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sources, TrafficIncidentOverlayConfig> {
-    private static lastInstanceIndex;
-    private instanceIndex;
     private lastResult;
     private lastFeatureIds;
     private lastFocusIds;
@@ -9902,7 +10234,7 @@ export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sour
     static get(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayConfig): Promise<TrafficIncidentOverlayModule>;
     private constructor();
     /** @ignore */
-    protected _initSourcesWithLayers(config?: TrafficIncidentOverlayConfig, restore?: boolean): Sources;
+    protected _initSourcesWithLayers(config?: TrafficIncidentOverlayConfig, _restore?: boolean): Sources;
     /** @ignore */
     protected _applyConfig(config: TrafficIncidentOverlayConfig | undefined): TrafficIncidentOverlayConfig | undefined;
     private applyBeforeLayer;
@@ -10211,7 +10543,7 @@ export declare class TrafficIncidentsModule extends AbstractMapModule<TrafficInc
      * @ignore
      */
     protected _initSourcesWithLayers(): {
-        trafficIncidents: StyleSourceWithLayers<SourceSpecification, Source>;
+        trafficIncidents: StyleSourceWithLayers< SourceSpecification, Source>;
     };
     /**
      * @ignore