@reuters-graphics/graphics-components 3.7.0 → 3.9.0

package/dist/components/Geocoder/Geocoder.svelte

@@ -2,6 +2,7 @@
 <script lang="ts">
   import { onDestroy } from 'svelte';
   import { geocode, type GeocodeFeature, type GeocodeOptions } from './geocode';
+  import { normalizeMinLength, normalizeDebounceMs } from './normalize';
   import MagnifyingGlass from '../SearchInput/components/MagnifyingGlass.svelte';
   import X from '../SearchInput/components/X.svelte';
 
@@ -12,12 +13,25 @@
     searchPlaceholder?: string;
     /** Callback fired when a location is selected from the results. */
     onselect?: (location: { lng: number; lat: number; name: string }) => void;
+    /**
+     * Minimum number of characters before a request is made. Raising this
+     * cuts the number of paid geocoding requests per search. Defaults to 2.
+     */
+    minLength?: number;
+    /**
+     * Debounce window in milliseconds between the last keystroke and the
+     * request. Raising this fires fewer requests while the user is still
+     * typing (each request is billed). Defaults to 300.
+     */
+    debounceMs?: number;
   }
 
   let {
     accessToken,
     searchPlaceholder = 'Search for a location',
     onselect,
+    minLength = 2,
+    debounceMs = 300,
     autocomplete = true,
     bbox,
     country,
@@ -44,12 +58,22 @@
   let debounceTimer: ReturnType<typeof setTimeout>;
   let abortController: AbortController | null = null;
 
+  // Normalize the throttling props so a non-numeric value passed via markup
+  // (e.g. `minLength="two"`) can't coerce to NaN and disable the gate — which
+  // would bill a request on every keystroke. Fall back to the documented
+  // defaults, clamped to sane floors.
+  let effectiveMinLength = $derived(normalizeMinLength(minLength));
+  let effectiveDebounceMs = $derived(normalizeDebounceMs(debounceMs));
+
   function handleInput() {
     selectedIndex = -1;
     clearTimeout(debounceTimer);
     abortController?.abort();
 
-    if (query.length < 2) {
+    // Trim first so whitespace-only input (e.g. "  ") doesn't clear the gate
+    // and bill a request for an empty search.
+    const trimmed = query.trim();
+    if (trimmed.length < effectiveMinLength) {
       suggestions = [];
       return;
     }
@@ -58,7 +82,7 @@
       abortController = new AbortController();
       try {
         suggestions = await geocode(
-          query,
+          trimmed,
           {
             accessToken,
             autocomplete,
@@ -78,7 +102,7 @@
         if (e instanceof DOMException && e.name === 'AbortError') return;
         console.error('Geocoder error:', e);
       }
-    }, 300);
+    }, effectiveDebounceMs);
   }
 
   onDestroy(() => {

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

@@ -10,6 +10,17 @@ interface Props extends Omit<GeocodeOptions, 'accessToken'> {
         lat: number;
         name: string;
     }) => void;
+    /**
+     * Minimum number of characters before a request is made. Raising this
+     * cuts the number of paid geocoding requests per search. Defaults to 2.
+     */
+    minLength?: number;
+    /**
+     * Debounce window in milliseconds between the last keystroke and the
+     * request. Raising this fires fewer requests while the user is still
+     * typing (each request is billed). Defaults to 300.
+     */
+    debounceMs?: number;
 }
 /** `Geocoder` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-controls-geocoder--docs) */
 declare const Geocoder: import("svelte").Component<Props, {}, "">;

package/dist/components/Geocoder/normalize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Coercion helpers for the Geocoder's request-throttling props.
+ *
+ * These props can arrive as strings when set via markup (e.g.
+ * `minLength="two"`), so a non-numeric value must not be trusted directly: a
+ * `NaN` would disable the length gate or the debounce and bill a Mapbox request
+ * on every keystroke. Both helpers fall back to the documented defaults and
+ * clamp to sane floors.
+ */
+/**
+ * Coerce a consumer-supplied `minLength` to a safe integer of at least 1.
+ * Invalid or sub-1 values fall back to `fallback` (default 2).
+ */
+export declare function normalizeMinLength(value: unknown, fallback?: number): number;
+/**
+ * Coerce a consumer-supplied `debounceMs` to a finite, non-negative number.
+ * Invalid or negative values fall back to `fallback` (default 300).
+ */
+export declare function normalizeDebounceMs(value: unknown, fallback?: number): number;

package/dist/components/Geocoder/normalize.js

@@ -0,0 +1,25 @@
+/**
+ * Coercion helpers for the Geocoder's request-throttling props.
+ *
+ * These props can arrive as strings when set via markup (e.g.
+ * `minLength="two"`), so a non-numeric value must not be trusted directly: a
+ * `NaN` would disable the length gate or the debounce and bill a Mapbox request
+ * on every keystroke. Both helpers fall back to the documented defaults and
+ * clamp to sane floors.
+ */
+/**
+ * Coerce a consumer-supplied `minLength` to a safe integer of at least 1.
+ * Invalid or sub-1 values fall back to `fallback` (default 2).
+ */
+export function normalizeMinLength(value, fallback = 2) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
+}
+/**
+ * Coerce a consumer-supplied `debounceMs` to a finite, non-negative number.
+ * Invalid or negative values fall back to `fallback` (default 300).
+ */
+export function normalizeDebounceMs(value, fallback = 300) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}

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.9.0",
   "type": "module",
   "private": false,
   "homepage": "https://reuters-graphics.github.io/graphics-components",