@tomtom-org/maps-sdk 0.46.12 → 0.47.0

package/map/dist/index.d.ts

@@ -2286,37 +2286,28 @@ declare type DisplayInstructionArrows = FeatureCollection<Point, Instruction & D
 declare type DisplayInstructions = FeatureCollection<LineString, Instruction & DisplayRouteRelatedProps>;
 
 /**
- * Place base and display properties combined.
- *
- * Merges complete place information from the core API with display-specific
- * properties for rendering on the map.
- *
- * @remarks
- * This is the full type used by the PlacesModule for rendering search results,
- * POIs, and other location markers on the map. It combines:
- * - Geographic data (coordinates, address)
- * - Place metadata (POI info, opening hours, etc.)
- * - Display properties (icon, title, category)
- * - Interactive state (event handling)
+ * Full property shape used by the PlacesModule when rendering a place: the
+ * core place data ({@link CommonPlaceProps}) merged with the display-only
+ * fields the module attaches ({@link PlaceDisplayProps}).
  *
  * @example
  * ```typescript
  * const place: DisplayPlaceProps = {
- *   type: 'Point',
- *   position: { lon: 4.9, lat: 52.3 },
+ *   type: 'POI',
+ *   poi: {
+ *     name: 'Central Station',
+ *     categories: ['RAILWAY_STATION'],
+ *   },
  *   address: {
  *     streetName: 'Damrak',
  *     municipalitySubdivision: 'Amsterdam',
- *     countryCode: 'NL'
- *   },
- *   poi: {
- *     name: 'Central Station',
- *     categories: ['RAILWAY_STATION']
+ *     countryCode: 'NL',
  *   },
  *   id: 'place-123',
  *   title: 'Amsterdam Central Station',
- *   iconID: 'poi-transit',
- *   category: 'RAILWAY_STATION'
+ *   iconID: 'poi-railway_station',
+ *   category: 'railway_station',
+ *   group: 'transport',
  * };
  * ```
  *
@@ -3920,11 +3911,18 @@ export declare const getLineForegroundWidth: (size?: RouteWidth) => ExpressionSp
  */
 export declare const getLineOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
 
+/**
+ * Maps a Place to the base map POI group used by the style's `text-color` and
+ * `POI - Micro` icon expressions (e.g., `eat_and_drink`, `lodging`, `driving`).
+ * @ignore
+ */
+export declare const getPOIGroupForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
+
 /**
  * Maps a Place category to the poi layer one, so the latter's style can apply it.
  * @ignore
  */
-export declare const getPOILayerCategoryForPlace: (place: Place) => string | undefined;
+export declare const getPOILayerCategoryForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
 
 /**
  * Gets the specified filtered categories icon IDs to be used in map filtering.
@@ -4903,29 +4901,38 @@ export declare type MultiSyntaxFilter = {
 };
 
 /**
- * Properties to display a place on the map.
- *
- * Extends basic place information with display-specific properties needed
- * for rendering markers, icons, and labels on the map.
+ * Properties attached to a place feature for rendering on the map.
  *
  * @remarks
- * **Use Cases:**
- * - Search result markers
- * - POI markers
- * - Custom location pins
- * - EV charging station markers
- *
- * These properties control how the place appears visually on the map,
- * including its icon, label, and interactive states.
+ * Extends the source place with display-only fields consumed by the places
+ * layer stack. Which fields are populated depends on the active
+ * {@link PlacesTheme | theme}:
+ *
+ * - Every theme uses {@link PlaceDisplayProps.iconID | iconID} — the sprite name
+ *   the main layer's `icon-image` expression binds to via `['get', 'iconID']`.
+ *   The base map's POI-Micro-like layer inherits the style's `['get','group']`
+ *   expression verbatim, so custom `PlaceIconConfig.categoryIcons` sprites only
+ *   apply to the `main` layer.
+ * - The `base-map` theme additionally populates
+ *   {@link PlaceDisplayProps.category | category} and
+ *   {@link PlaceDisplayProps.group | group} so the base map style's own
+ *   `text-color` expression — and the POI-Micro layer's `icon-image` expression
+ *   — resolve against the place feature just as they do for native POIs.
  *
  * @example
  * ```typescript
- * const locationProps: LocationDisplayProps = {
+ * const pinPlaceProps: PlaceDisplayProps = {
  *   id: 'place-123',
  *   title: 'Central Station',
  *   iconID: 'poi-transit',
- *   category: 'RAILWAY_STATION',
- *   eventState: 'hover'
+ * };
+ *
+ * const baseMapPlaceProps: PlaceDisplayProps = {
+ *   id: 'place-123',
+ *   title: 'Central Station',
+ *   iconID: 'poi-railway_station',
+ *   category: 'railway_station',
+ *   group: 'transport',
  * };
  * ```
  *
@@ -4936,87 +4943,81 @@ export declare type PlaceDisplayProps = {
      * Unique identifier for the place feature.
      *
      * @remarks
-     * MapLibre does not reuse the feature IDs. Either we generate it on the fly
-     * or use the one from properties via promotedId value.
-     *
-     * Used for:
-     * - Feature identification in events
-     * - State management
-     * - Data updates
+     * MapLibre does not reuse the feature IDs, so we either generate one on the
+     * fly or promote the one from `properties.id` via the source's `promoteId`
+     * option. Used for feature identification in events, hit-testing, and data
+     * updates.
      *
      * @example
      * ```typescript
      * id: 'place-123'
-     * id: 'poi-456'
      * ```
      */
     id: string;
     /**
-     * Display title for the place on the map.
+     * Text label rendered next to the place marker.
      *
      * @remarks
-     * Optional text label shown near the place marker. If not provided,
-     * no text label will be displayed.
-     *
-     * **Common Sources:**
-     * - POI name (e.g., "Starbucks")
-     * - Address (e.g., "123 Main Street")
-     * - Custom label (e.g., "Meeting Point")
+     * Optional — when absent no label is drawn. Typically sourced from the POI
+     * name or free-form address, but can be any custom string (e.g., configured
+     * via `PlacesModuleConfig.text.title`).
      *
      * @example
      * ```typescript
      * title: 'Amsterdam Central Station'
-     * title: 'Starbucks'
-     * title: '123 Main Street'
-     * title: undefined  // No label
      * ```
      */
     title?: string;
     /**
-     * Icon ID referencing the map style sprite.
+     * Sprite image ID used to draw the place marker.
      *
      * @remarks
-     * References an icon image in the map's sprite sheet. The icon must exist
-     * in the map style or be added programmatically.
-     *
-     * **Icon Types:**
-     * - Built-in POI icons (e.g., 'poi-restaurant', 'poi-hotel')
-     * - Custom icons added to the sprite
-     * - Pin/marker icons (e.g., 'pin-red', 'pin-blue')
+     * The main layer binds `icon-image` to `['get', 'iconID']`, so the sprite
+     * named here is what renders. The base map's POI-Micro-like layer inherits
+     * the style's group-driven expression verbatim and ignores this value. The
+     * sprite name is resolved per theme: `pin` / `circle-icon` pick a built-in
+     * sprite; `base-map` picks the base map's `poi-<category>` sprite; a custom
+     * `PlaceIconConfig.categoryIcons` entry overrides the default for the main
+     * layer on any theme.
      *
      * @example
      * ```typescript
-     * iconID: 'poi-restaurant'
-     * iconID: 'pin-red'
-     * iconID: 'custom-marker'
+     * iconID: '7315'              // pin theme sprite
+     * iconID: 'poi-restaurant'    // circle-icon / base-map theme sprite
+     * iconID: 'custom-marker-0'   // user-provided custom icon
      * ```
      */
     iconID: string;
     /**
-     * Map-style-compatible display category, mostly applicable for base-map places.
+     * Base map style POI category the place should be rendered as.
      *
      * @remarks
-     * Used to match the place with a POI category in the map style, enabling
-     * category-specific styling and filtering.
-     *
-     * **Common Categories:**
-     * - RESTAURANT
-     * - HOTEL_MOTEL
-     * - GAS_STATION
-     * - PARKING_GARAGE
-     * - SHOPPING
-     *
-     * Optional - only needed when using base-map styling or category-based filtering.
+     * Populated only for the `base-map` theme. Values are the lowercased
+     * identifiers used by the base map style (derived via
+     * {@link toBaseMapPOICategory}). Drives the inherited `text-color`
+     * expression on the main/selected POI-like layers.
      *
      * @example
      * ```typescript
-     * category: 'RESTAURANT'
-     * category: 'HOTEL_MOTEL'
-     * category: 'EV_CHARGING_STATION'
-     * category: undefined  // No category association
+     * category: 'restaurant'
+     * category: 'hotel_or_motel'
+     * category: 'charging_location'
      * ```
      */
     category?: string;
+    /**
+     * Base map style POI group the place belongs to.
+     *
+     * @remarks
+     * Populated only for the `base-map` theme. Drives the inherited
+     * `text-color` expression on the base map's POI layers.
+     * Valid values are those produced by {@link toBaseMapPOIGroup} — e.g.,
+     * `eat_and_drink`, `lodging`, `driving`, `transport`, `shopping`,
+     * `healthcare`, `finance`, `cultural`, `leisure`, `sport`, `outdoor`,
+     * `protected`, `public`, `religion`, `military`, `business`, `education`,
+     * `parking`.
+     */
+    group?: string;
 } & SupportsEvents & Anything;
 
 /**
@@ -5141,6 +5142,18 @@ export declare type PlaceLayersConfig = {
      * This layer renders places that are not in a highlighted/selected state.
      */
     main?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+    /**
+     * Micro place marker layer specification.
+     *
+     * @remarks
+     * Always registered and stacked below the `main` layer, but only renders features
+     * when the `base-map` theme is active — in that mode it mirrors the map style's
+     * `POI - Micro` layer so place markers blend with the base map's lower-density
+     * POI rendering. For other themes the layer is hidden via
+     * `layout.visibility = 'none'` and acts as a no-op, making theme switches cheap
+     * (no add/remove layer churn).
+     */
+    micro?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
     /**
      * Selected place marker layer specification.
      *
@@ -5163,7 +5176,7 @@ export declare type PlaceLayersConfig = {
  *
  * @remarks
  * **Features:**
- * - Multiple marker styles (pin, circle, POI-like)
+ * - Multiple marker styles (pin, circle-icon, base-map POI-like)
  * - Custom icons per POI category
  * - Text labels with styling options
  * - Data-driven styling via MapLibre expressions
@@ -5173,8 +5186,8 @@ export declare type PlaceLayersConfig = {
  *
  * **Marker Styles:**
  * - `pin`: Traditional teardrop-shaped map pins
- * - `circle`: Simple circular markers
- * - `base-map`: Mimics built-in POI layer styling
+ * - `circle-icon`: Simple circular markers (previously named `circle`)
+ * - `base-map`: Mimics the map's built-in POI layer styling (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
  *
  * **EV Charging Station Availability:**
  * When displaying EV charging stations with availability data from
@@ -5279,8 +5292,8 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * @remarks
      * **Available Themes:**
      * - `pin`: Traditional teardrop-shaped map pins
-     * - `circle`: Simple circular markers
-     * - `base-map`: Mimics the map's built-in POI layer style with category icons
+     * - `circle-icon`: Simple circular markers (previously named `circle`)
+     * - `base-map`: Mimics the map's built-in POI layer style with category icons (combines `main`, `selected`, and `micro`). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
      *
      * Changes apply immediately to all currently shown places. Other configuration
      * properties (icon config, text config) remain unchanged.
@@ -5291,7 +5304,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
      * placesModule.applyTheme('pin');
      *
      * // Use simple circles
-     * placesModule.applyTheme('circle');
+     * placesModule.applyTheme('circle-icon');
      *
      * // Match map's POI style (ideal to blend in)
      * placesModule.applyTheme('base-map');
@@ -5364,6 +5377,7 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
         [key: string]: any;
     }): void;
     private updateLayersAndData;
+    private applyPlacesVisibility;
     private setupImages;
     private updateData;
     /**
@@ -5626,12 +5640,12 @@ declare type PlacesSourcesAndLayers = {
  * @remarks
  * **Available Styles:**
  * - `pin`: Traditional map pin markers (teardrop shape)
- * - `circle`: Simple circular markers
- * - `base-map`: Mimics the map's built-in POI layer style with category icons
+ * - `circle-icon`: Simple circular markers (previously named `circle`)
+ * - `base-map`: Mimics the map's built-in POI layer style with category icons (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
  *
  * @group Places
  */
-export declare type PlacesTheme = 'pin' | 'circle' | 'base-map';
+export declare type PlacesTheme = 'pin' | 'circle-icon' | 'base-map';
 
 /**
  * Configuration for place text labels.
@@ -8080,6 +8094,11 @@ export declare const themedGeometryConfig: (palette?: ColorPaletteOptions, befor
  */
 export declare const toBaseMapPOICategory: (category: POICategory) => string;
 
+/**
+ * @ignore
+ */
+export declare const toBaseMapPOIGroup: (category: POICategory) => string | undefined;
+
 /**
  * Layer to be added to the existing style, and may include extra config such as the ID of the layer to add it under.
  * * e.g. GeoJSON layers.