@reuters-graphics/graphics-components 3.7.0 → 3.8.0

package/dist/components/TileMap/TileMap.svelte

@@ -21,6 +21,7 @@
   import GraphicBlock from '../GraphicBlock/GraphicBlock.svelte';
   import type { ContainerWidth } from '../@types/global';
   import type { ProjectionSpecification } from 'maplibre-gl';
+  import { emphasizePlaceLabels } from './labels';
   import 'maplibre-gl/dist/maplibre-gl.css';
 
   interface Props {
@@ -65,6 +66,13 @@
      * Map style URL
      */
     styleUrl?: string;
+    /**
+     * Darken the basemap's place labels and give them a strong white halo, so
+     * city/region names stay readable over colored data layers. Applied once on
+     * map load; a no-op on styles without `place` labels (e.g. non-default
+     * `styleUrl`s), so it degrades gracefully.
+     */
+    emphasizeLabels?: boolean;
     /**
      * Map height (default: '500px')
      */
@@ -101,6 +109,7 @@
     projection,
     interactive = true,
     styleUrl = 'https://graphics.thomsonreuters.com/reuters-protomaps/style.json',
+    emphasizeLabels = false,
     height = '500px',
     width = 'normal',
     textWidth = 'normal',
@@ -155,6 +164,28 @@
         );
       }
 
+      // Darken the basemap's place labels so they read over data layers. Some
+      // styles keep applying their own label paint for a moment after the style
+      // loads, so a single call at `load` can be overridden and leave the
+      // labels their default (lighter) color. Apply on the first `styledata`
+      // where the place labels are present, then stop listening.
+      if (emphasizeLabels) {
+        const applyLabelEmphasis = () => {
+          if (!map) return;
+          const hasPlaceLabels = map
+            .getStyle()
+            ?.layers?.some(
+              (l) =>
+                l.type === 'symbol' &&
+                (l as { 'source-layer'?: string })['source-layer'] === 'place'
+            );
+          if (!hasPlaceLabels) return;
+          emphasizePlaceLabels(map);
+          map.off('styledata', applyLabelEmphasis);
+        };
+        map.on('styledata', applyLabelEmphasis);
+      }
+
       // Call the callback when map is ready
       map.on('load', () => {
         if (!map) return;

package/dist/components/TileMap/TileMap.svelte.d.ts

@@ -45,6 +45,13 @@ interface Props {
      * Map style URL
      */
     styleUrl?: string;
+    /**
+     * Darken the basemap's place labels and give them a strong white halo, so
+     * city/region names stay readable over colored data layers. Applied once on
+     * map load; a no-op on styles without `place` labels (e.g. non-default
+     * `styleUrl`s), so it degrades gracefully.
+     */
+    emphasizeLabels?: boolean;
     /**
      * Map height (default: '500px')
      */

package/dist/components/TileMap/TileMapLayer.svelte

@@ -4,6 +4,7 @@
   import type { Map as MaplibreMap, GeoJSONSource } from 'maplibre-gl';
   import type { Writable } from 'svelte/store';
   import type { GeoJSON } from 'geojson';
+  import { findFirstSymbolLayerId } from './labels';
 
   interface Props {
     /**
@@ -39,6 +40,12 @@
      * Layer to insert before (for layer ordering)
      */
     beforeId?: string;
+    /**
+     * Insert this layer beneath the basemap's labels, so place names and other
+     * symbol layers stay readable on top of it. Ignored when `beforeId` is set
+     * (that takes precedence). A no-op on styles with no symbol layers.
+     */
+    beneathLabels?: boolean;
     /**
      * Minimum zoom level to display layer
      */
@@ -60,6 +67,7 @@
     paint = {},
     layout = {},
     beforeId,
+    beneathLabels = false,
     minZoom,
     maxZoom,
     filter,
@@ -146,7 +154,11 @@
         if (maxZoom !== undefined) layerConfig.maxzoom = maxZoom;
         if (filter) layerConfig.filter = filter;
 
-        map.addLayer(layerConfig as never, beforeId);
+        // An explicit `beforeId` wins; otherwise `beneathLabels` inserts the
+        // layer just below the first symbol (label) layer so labels stay on top.
+        const insertBefore =
+          beforeId ?? (beneathLabels ? findFirstSymbolLayerId(map) : undefined);
+        map.addLayer(layerConfig as never, insertBefore);
       }
 
       isInitialized = true;

package/dist/components/TileMap/TileMapLayer.svelte.d.ts

@@ -24,6 +24,12 @@ interface Props {
      * Layer to insert before (for layer ordering)
      */
     beforeId?: string;
+    /**
+     * Insert this layer beneath the basemap's labels, so place names and other
+     * symbol layers stay readable on top of it. Ignored when `beforeId` is set
+     * (that takes precedence). A no-op on styles with no symbol layers.
+     */
+    beneathLabels?: boolean;
     /**
      * Minimum zoom level to display layer
      */

package/dist/components/TileMap/labels.d.ts

@@ -0,0 +1,34 @@
+import type { Map as MaplibreMap } from 'maplibre-gl';
+/**
+ * Find the first symbol (label) layer in the map's current style, or undefined.
+ * Symbol layers are the basemap's place names, road labels, etc. Inserting a
+ * data layer *before* this id keeps every label above the data.
+ *
+ * @see https://docs.mapbox.com/mapbox-gl-js/example/geojson-layer-in-stack/
+ */
+export declare function findFirstSymbolLayerId(map: MaplibreMap): string | undefined;
+/** Options for {@link emphasizePlaceLabels}. */
+export interface EmphasizeLabelsOptions {
+    /** Text color for place labels. Default `#1a1a1a` (near-black). */
+    textColor?: string;
+    /** Halo color. Default solid white. */
+    haloColor?: string;
+    /** Halo width, in px. Default `1.6`. */
+    haloWidth?: number;
+}
+/**
+ * Darken the basemap's populated-place labels (cities, towns, capitals, …) and
+ * give them a strong white halo so they stay legible on top of colored data
+ * overlays.
+ *
+ * The default protomaps style fades place labels with a zoom-driven
+ * `text-opacity` (city labels only reach full strength around zoom 9), so this
+ * also pins `text-opacity` to 1 — otherwise the near-black color reads as gray
+ * at the low-to-mid zooms typical of a choropleth.
+ *
+ * Targets the `place` source-layer symbol layers of the default Reuters
+ * protomaps style. On a style that doesn't have them it's a **no-op** (the
+ * per-layer checks and `try/catch` make it degrade gracefully), so it's safe to
+ * call regardless of `styleUrl`.
+ */
+export declare function emphasizePlaceLabels(map: MaplibreMap, opts?: EmphasizeLabelsOptions): void;

package/dist/components/TileMap/labels.js

@@ -0,0 +1,55 @@
+/**
+ * Find the first symbol (label) layer in the map's current style, or undefined.
+ * Symbol layers are the basemap's place names, road labels, etc. Inserting a
+ * data layer *before* this id keeps every label above the data.
+ *
+ * @see https://docs.mapbox.com/mapbox-gl-js/example/geojson-layer-in-stack/
+ */
+export function findFirstSymbolLayerId(map) {
+    const layers = map.getStyle()?.layers;
+    if (!layers)
+        return undefined;
+    for (const layer of layers) {
+        if (layer.type === 'symbol')
+            return layer.id;
+    }
+    return undefined;
+}
+/**
+ * Darken the basemap's populated-place labels (cities, towns, capitals, …) and
+ * give them a strong white halo so they stay legible on top of colored data
+ * overlays.
+ *
+ * The default protomaps style fades place labels with a zoom-driven
+ * `text-opacity` (city labels only reach full strength around zoom 9), so this
+ * also pins `text-opacity` to 1 — otherwise the near-black color reads as gray
+ * at the low-to-mid zooms typical of a choropleth.
+ *
+ * Targets the `place` source-layer symbol layers of the default Reuters
+ * protomaps style. On a style that doesn't have them it's a **no-op** (the
+ * per-layer checks and `try/catch` make it degrade gracefully), so it's safe to
+ * call regardless of `styleUrl`.
+ */
+export function emphasizePlaceLabels(map, opts = {}) {
+    const { textColor = '#1a1a1a', haloColor = 'rgba(255, 255, 255, 1)', haloWidth = 1.6, } = opts;
+    const layers = map.getStyle()?.layers;
+    if (!layers)
+        return;
+    for (const layer of layers) {
+        if (layer.type !== 'symbol')
+            continue;
+        const sourceLayer = layer['source-layer'];
+        if (sourceLayer !== 'place')
+            continue;
+        try {
+            map.setPaintProperty(layer.id, 'text-color', textColor);
+            map.setPaintProperty(layer.id, 'text-halo-color', haloColor);
+            map.setPaintProperty(layer.id, 'text-halo-width', haloWidth);
+            map.setPaintProperty(layer.id, 'text-halo-blur', 0);
+            map.setPaintProperty(layer.id, 'text-opacity', 1);
+        }
+        catch {
+            /* layer isn't paintable in this style; skip it */
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reuters-graphics/graphics-components",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "type": "module",
   "private": false,
   "homepage": "https://reuters-graphics.github.io/graphics-components",