@rcpch/imd-map 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -8,6 +8,38 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-05-16
+
+### Added
+
+- Added `channel_islands` as a supported nation value across the public API (`initialNation`, `setNation`, and nation-aware styling).
+- Added resolver and filter support for `channel_islands` in nation filtering and era resolution.
+- Added automated smoke tests for standalone example pages to verify they are served and include expected map initialization and patient plotting hooks.
+
+### Changed
+
+- Updated Channel Islands era behavior to honour the requested era (`2011` or `2021`) while rendering 2024 boundaries in both table families.
+- Included Channel Islands in all-UK nation color matching so all-UK choropleth rendering handles `nation: channel_islands` explicitly.
+- Added default neutral base color wiring for Channel Islands to support no-IMD-data rendering.
+
+### Documentation
+
+- Updated README and AGENTS guidance for Channel Islands nation support and era semantics.
+
+## [0.3.1] — 2026-04-28
+
+### Added
+
+- Optional tile API key support via `tilesApiKey` and `tilesApiKeyParam` options in `CreateImdMapOptions`.
+- Tile API key query parameters are appended to all choropleth and boundary overlay tile requests.
+- Customizable query parameter name for tile auth (defaults to `api_key`).
+- Unit test coverage for tile URL builder with optional auth and auth propagation across overlays.
+
+### Documentation
+
+- Updated README runtime tile configuration section with tile auth options and example usage.
+- Added note that browser-delivered keys are non-secret and primarily useful for operational traffic control (rate limiting, revocation, origin restrictions).
+
 ## [0.3.0] — 2026-04-27
 
 ### Changed

package/README.md

@@ -201,6 +201,24 @@ Tile URL resolution precedence:
 
 The library source contains **no hardcoded tile URLs**.
 
+Optional tile auth query options:
+
+- `tilesApiKey`: appends a query value to all choropleth and overlay tile requests
+- `tilesApiKeyParam`: query parameter name for `tilesApiKey` (default: `api_key`)
+
+Example:
+
+```js
+createImdMap({
+  container: 'map',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  tilesApiKey: 'switchable-browser-token',
+  tilesApiKeyParam: 'key',
+});
+```
+
+This is useful for revoking abusive traffic quickly, but browser-delivered keys must still be treated as non-secret.
+
 ### Overlay boundary tile contract
 
 Boundary overlays (local authority, NHSER, ICB, LHB) are requested from schema-qualified table ids and rendered with the same schema-qualified `source-layer` name. Example:
@@ -218,22 +236,23 @@ Bring your own overlay configuration (custom overlay table/layer names via libra
 
 The `era` option refers to the boundary year used for the LSOA geography, not the IMD publication year.
 
-For England, the supported pairings are:
+For England and Channel Islands, the supported pairings are:
 
-- `2011` era = 2011 LSOA boundaries + 2019 IMD data
-- `2021` era = 2021 LSOA boundaries + 2025 IMD data
+- `2011` era = 2011 LSOA boundaries + 2019 IMD data (England only)
+- `2021` era = 2021 LSOA boundaries + 2025 IMD data (England only); Channel Islands on 2024 boundaries
 
 | Nation | Requested era | Effective era |
 |---|---|---|
 | `all` | `2011` or `2021` | as requested |
 | `england` | `2011` or `2021` | as requested |
+| `channel_islands` | `2011` or `2021` | as requested (2024 boundaries in both) |
 | `wales` | any | always `2011` |
 | `scotland` | any | always `2011` |
 | `northern_ireland` | any | always `2011` |
 
 When the effective era differs from the requested era, `onWarning` is called with code `ERA_OVERRIDE`.
 
-For all-UK maps, `initialEra: '2021'` now uses the mixed-vintage `uk_master_2021_*` tables: England renders with 2021 LSOA boundaries and 2025 IMD data, while Wales, Scotland, and Northern Ireland continue to render from their existing older datasets within the same UK tile family. Use `initialEra: '2011'` when you want the older England 2011 LSOA + 2019 IMD view alongside the existing Welsh and other nation data.
+For all-UK maps, `initialEra: '2021'` now uses the mixed-vintage `uk_master_2021_*` tables: England renders with 2021 LSOA boundaries and 2025 IMD data, Channel Islands renders with 2024 boundaries, while Wales, Scotland, and Northern Ireland continue to render from their existing older datasets within the same UK tile family. Use `initialEra: '2011'` when you want the older England 2011 LSOA + 2019 IMD view alongside the existing Welsh and other nation data.
 
 This means you can instantiate two separate UK maps in the same application, choosing the England boundary/IMD pairing by era:
 
@@ -276,6 +295,7 @@ createImdMap({
         wales: '#1a9641',
         scotland: '#2b83ba',
         northern_ireland: '#7f7f7f',
+        channel_islands: '#d1d5db',
       },
       // 10 hex colors, index 0 = decile 1 (most deprived)
       fallbackDecileColors: ['#7a0036', ...],
@@ -407,6 +427,8 @@ map.setStyle({ tooltip: { areaLabel: 'Local area' } });
 |---|---|---|---|
 | `container` | `string \| HTMLElement` | — | DOM element ID or element reference |
 | `tilesBaseUrl` | `string` | — | Base URL of the tile server |
+| `tilesApiKey` | `string` | — | Optional API key appended to tile URLs as a query parameter |
+| `tilesApiKeyParam` | `string` | `'api_key'` | Query parameter name used for `tilesApiKey` |
 | `initialNation` | `Nation` | `'all'` | Starting nation filter |
 | `initialEra` | `Era` | `'2021'` | Requested era (may be overridden) |
 | `enableLocalAuthorityOverlay` | `boolean` | `false` | Show local authority boundary overlay at startup |

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { FeatureCollection, Point, Feature } from 'geojson';
 
-type Nation = 'all' | 'england' | 'wales' | 'scotland' | 'northern_ireland';
+type Nation = 'all' | 'england' | 'wales' | 'scotland' | 'northern_ireland' | 'channel_islands';
 type Era = '2011' | '2021';
 interface ChoroplethStyleOptions {
     /** Per-nation arrays of 10 hex colors, index 0 = decile 1 (most deprived). */
@@ -183,6 +183,10 @@ interface CreateImdMapOptions {
     container: string | HTMLElement;
     /** Base URL of the tile server. Required for choropleth rendering. */
     tilesBaseUrl?: string;
+    /** Optional API key appended to tile URLs as a query string parameter. */
+    tilesApiKey?: string;
+    /** Query parameter name used for tilesApiKey. Default: api_key. */
+    tilesApiKeyParam?: string;
     initialNation?: Nation;
     initialEra?: Era;
     showDefaultControls?: boolean;

package/dist/index.esm.js

@@ -9,6 +9,8 @@ function resolveEffectiveEra(nation, requestedEra) {
       return requestedEra;
     case "england":
       return requestedEra;
+    case "channel_islands":
+      return requestedEra;
     case "wales":
     case "scotland":
     case "northern_ireland":
@@ -29,9 +31,13 @@ var ZOOM_TIERS = [
 function resolveFullTableName(effectiveEra, tier) {
   return `public.uk_master_${effectiveEra}_${tier}`;
 }
-function buildTileUrl(tilesBaseUrl, fullTableName) {
+function buildTileUrl(tilesBaseUrl, fullTableName, auth) {
   const base = tilesBaseUrl.replace(/\/$/, "");
-  return `${base}/${fullTableName}/{z}/{x}/{y}.pbf`;
+  const tileUrl = `${base}/${fullTableName}/{z}/{x}/{y}.pbf`;
+  if (!auth?.apiKey) return tileUrl;
+  const paramName = auth.apiKeyParam?.trim() || "api_key";
+  const separator = tileUrl.includes("?") ? "&" : "?";
+  return `${tileUrl}${separator}${encodeURIComponent(paramName)}=${encodeURIComponent(auth.apiKey)}`;
 }
 function resolveNationFilter(nation) {
   if (nation === "all") return null;
@@ -60,11 +66,11 @@ function choroplethSourceId(tier) {
 ZOOM_TIERS.map((t) => choroplethSourceId(t.tier));
 var PATIENTS_SOURCE_ID = "rcpch-imd-patients";
 var LEAD_CENTRE_SOURCE_ID = "rcpch-imd-lead-centre";
-function addOrUpdateChoroplethSources(map, tilesBaseUrl, effectiveEra) {
+function addOrUpdateChoroplethSources(map, tilesBaseUrl, effectiveEra, tileAuth) {
   for (const { tier } of ZOOM_TIERS) {
     const sourceId = choroplethSourceId(tier);
     const fullTableName = resolveFullTableName(effectiveEra, tier);
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -113,6 +119,7 @@ var DEFAULT_BASE_COLORS_BY_NATION = {
   wales: "#1a9641",
   scotland: "#2b83ba",
   northern_ireland: "#7f7f7f",
+  channel_islands: "#d1d5db",
   all: "#d7191c"
 };
 function clamp(value, min, max) {
@@ -230,7 +237,8 @@ var DEFAULT_STYLE = {
       england: DEFAULT_BASE_COLORS_BY_NATION.england,
       wales: DEFAULT_BASE_COLORS_BY_NATION.wales,
       scotland: DEFAULT_BASE_COLORS_BY_NATION.scotland,
-      northern_ireland: DEFAULT_BASE_COLORS_BY_NATION.northern_ireland
+      northern_ireland: DEFAULT_BASE_COLORS_BY_NATION.northern_ireland,
+      channel_islands: DEFAULT_BASE_COLORS_BY_NATION.channel_islands
     },
     fallbackDecileColors: generateDecileRampFromBaseColor(DEFAULT_BASE_COLORS_BY_NATION.england),
     fillOpacity: 0.7,
@@ -355,7 +363,7 @@ function buildColorExpression(nation, style) {
   if (nation !== "all") {
     return buildDecileColorExpression(getDecileColors(nation, style));
   }
-  const perNation = ["england", "wales", "scotland", "northern_ireland"].flatMap((n) => [n, buildDecileColorExpression(getDecileColors(n, style))]);
+  const perNation = ["england", "wales", "scotland", "northern_ireland", "channel_islands"].flatMap((n) => [n, buildDecileColorExpression(getDecileColors(n, style))]);
   return [
     "match",
     ["get", "nation"],
@@ -899,13 +907,13 @@ function localAuthoritySourceId(tier) {
 function localAuthorityLayerId(tier) {
   return `${LOCAL_AUTHORITY_LAYER_ID}-${tier}`;
 }
-function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style) {
+function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style, tileAuth) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = localAuthoritySourceId(tier);
     const layerId = localAuthorityLayerId(tier);
     const fullTableName = buildMvtLayerName(LOCAL_AUTHORITY_TABLE_PREFIX, tier);
     const sourceLayer = fullTableName;
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -972,13 +980,13 @@ function overlaySourceId(baseSourceId, tier) {
 function overlayLayerId(baseLayerId, tier) {
   return `${baseLayerId}-${tier}`;
 }
-function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
+function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, input) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = overlaySourceId(input.sourceId, tier);
     const layerId = overlayLayerId(input.layerId, tier);
     const fullTableName = buildMvtLayerName(input.tablePrefix, tier);
     const sourceLayer = fullTableName;
-    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
+    const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName, tileAuth);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
       existing.setTiles([tileUrl]);
@@ -1014,8 +1022,8 @@ function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
     });
   }
 }
-function addOrUpdateNhserOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateNhserOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: NHSER_SOURCE_ID,
     layerId: NHSER_LAYER_ID,
     tablePrefix: NHSER_TABLE_PREFIX,
@@ -1023,8 +1031,8 @@ function addOrUpdateNhserOverlay(map, tilesBaseUrl, style) {
     lineWidth: style.boundaries.nhserWidth ?? 1.5
   });
 }
-function addOrUpdateIcbOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateIcbOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: ICB_SOURCE_ID,
     layerId: ICB_LAYER_ID,
     tablePrefix: ICB_TABLE_PREFIX,
@@ -1032,8 +1040,8 @@ function addOrUpdateIcbOverlay(map, tilesBaseUrl, style) {
     lineWidth: style.boundaries.icbWidth ?? 1
   });
 }
-function addOrUpdateLhbOverlay(map, tilesBaseUrl, style) {
-  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, {
+function addOrUpdateLhbOverlay(map, tilesBaseUrl, style, tileAuth) {
+  addOrUpdateBoundaryOverlay(map, tilesBaseUrl, tileAuth, {
     sourceId: LHB_SOURCE_ID,
     layerId: LHB_LAYER_ID,
     tablePrefix: LHB_TABLE_PREFIX,
@@ -1377,6 +1385,10 @@ function createImdMap(options) {
   if (!tilesBaseUrl) {
     logger.warn("No tilesBaseUrl provided. Choropleth tiles will not load.");
   }
+  const tileAuth = {
+    apiKey: options.tilesApiKey,
+    apiKeyParam: options.tilesApiKeyParam
+  };
   let resolvedStyle = mergeStyle(DEFAULT_STYLE, options.style);
   let state = createInitialState(options.initialNation ?? "all", options.initialEra ?? "2021");
   if (options.enableLocalAuthorityOverlay) {
@@ -1473,22 +1485,22 @@ function createImdMap(options) {
     const canShowIcb = nation === "all" || nation === "england";
     const canShowLhb = nation === "all" || nation === "wales";
     if (state.overlays.localAuthority) {
-      addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideLocalAuthorityOverlay(map);
     }
     if (state.overlays.nhser && canShowNhser) {
-      addOrUpdateNhserOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateNhserOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideNhserOverlay(map);
     }
     if (state.overlays.icb && canShowIcb) {
-      addOrUpdateIcbOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateIcbOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideIcbOverlay(map);
     }
     if (state.overlays.lhb && canShowLhb) {
-      addOrUpdateLhbOverlay(map, tilesBaseUrl, resolvedStyle);
+      addOrUpdateLhbOverlay(map, tilesBaseUrl, resolvedStyle, tileAuth);
     } else {
       hideLhbOverlay(map);
     }
@@ -1522,10 +1534,13 @@ function createImdMap(options) {
     });
   }
   logger.debug(`tilesBaseUrl resolved to: "${tilesBaseUrl}"`);
+  if (tileAuth.apiKey) {
+    logger.debug("Tile API key is configured for tile URL requests.");
+  }
   map.on("load", () => {
     mapLoaded = true;
     if (tilesBaseUrl) {
-      addOrUpdateChoroplethSources(map, tilesBaseUrl, state.effectiveEra);
+      addOrUpdateChoroplethSources(map, tilesBaseUrl, state.effectiveEra, tileAuth);
       addChoroplethLayers(map, state.nation, state.effectiveEra, resolvedStyle);
     }
     applyOverlayVisibility();
@@ -1576,7 +1591,7 @@ function createImdMap(options) {
     if (mapLoaded && tilesBaseUrl) {
       if (eraChanged) {
         removeChoroplethLayers(map);
-        addOrUpdateChoroplethSources(map, tilesBaseUrl, newEffectiveEra);
+        addOrUpdateChoroplethSources(map, tilesBaseUrl, newEffectiveEra, tileAuth);
         addChoroplethLayers(map, newNation, newEffectiveEra, resolvedStyle);
       } else if (nationChanged) {
         updateChoroplethNationFilter(map, newNation);