@rcpch/imd-map 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -8,13 +8,21 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-04-27
+
+### Changed
+
+- Updated all-UK era resolution so `initialNation: 'all'` honours the requested era instead of always forcing `2011`.
+- Documented the mixed-vintage `uk_master_2021_*` UK tiles, where England uses 2021 LSOA boundaries with 2025 IMD data while Wales, Scotland, and Northern Ireland remain on their current older datasets.
+- Clarified in the public docs that `era` refers to the LSOA boundary year, not the IMD publication year, and documented the England pairings of `2011` → 2011 LSOAs + 2019 IMD and `2021` → 2021 LSOAs + 2025 IMD.
+
 ## [0.2.0] — 2026-04-26
 
 ### Changed
 
 - Switched local authority boundary overlay to zoom-tiered pg_tileserv tables (`public.la_tiles_z0_4`, `public.la_tiles_z5_7`, `public.la_tiles_z8_10`, `public.la_tiles_z11_14`) with tier-matched layer zoom windows.
 - Switched health boundary overlays to zoom-tiered pg_tileserv tables for NHS England regions (`public.nhser_tiles_2021_*`), ICBs (`public.icb_tiles_2023_*`), and Welsh LHBs (`public.lhb_tiles_2022_*`).
-- Corrected overlay `source-layer` usage to match pg_tileserv behavior (table name without `public.` schema prefix).
+- Corrected overlay `source-layer` usage to match deployed overlay vector tiles by using schema-qualified layer names (for example `public.la_tiles_z5_7`) and keeping `source-layer` equal to the URL table id.
 - Updated overlay visibility handling so hide/show applies across all zoom-tier boundary layers.
 
 ### Added

package/README.md

@@ -69,7 +69,7 @@ The UMD bundle includes MapLibre GL. No separate script tag required.
 ```html
 <div id="map" style="height: 600px"></div>
 
-<script src="https://cdn.jsdelivr.net/npm/@rcpch/imd-map@0.1.0/dist/umd/rcpch-imd-map.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@rcpch/imd-map@0.3.0/dist/umd/rcpch-imd-map.min.js"></script>
 <script>
   const map = RcpchImdMap.createImdMap({
     container: 'map',
@@ -201,13 +201,31 @@ Tile URL resolution precedence:
 
 The library source contains **no hardcoded tile URLs**.
 
+### 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:
+
+- URL table id: `public.la_tiles_z5_7`
+- `source-layer`: `public.la_tiles_z5_7`
+
+If you self-host boundary tiles, ensure each overlay PBF exposes the exact same layer name string as the table id used in the URL path.
+
+Bring your own overlay configuration (custom overlay table/layer names via library options) could be enabled in a future release. If you need this, please open a GitHub issue so contributors can prioritise and scope it.
+
 ---
 
 ## Nation and era rules
 
+The `era` option refers to the boundary year used for the LSOA geography, not the IMD publication year.
+
+For England, the supported pairings are:
+
+- `2011` era = 2011 LSOA boundaries + 2019 IMD data
+- `2021` era = 2021 LSOA boundaries + 2025 IMD data
+
 | Nation | Requested era | Effective era |
 |---|---|---|
-| `all` | any | always `2011` |
+| `all` | `2011` or `2021` | as requested |
 | `england` | `2011` or `2021` | as requested |
 | `wales` | any | always `2011` |
 | `scotland` | any | always `2011` |
@@ -215,6 +233,31 @@ The library source contains **no hardcoded tile URLs**.
 
 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.
+
+This means you can instantiate two separate UK maps in the same application, choosing the England boundary/IMD pairing by era:
+
+```js
+const historicalMap = createImdMap({
+  container: 'map-2011',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  initialNation: 'all',
+  initialEra: '2011',
+});
+
+const currentMap = createImdMap({
+  container: 'map-2021',
+  tilesBaseUrl: 'https://your-tile-server.example.com',
+  initialNation: 'all',
+  initialEra: '2021',
+});
+```
+
+In a patient-facing application, a common pattern would be:
+
+- patients before 2025 or 2026 cutoff: `initialEra: '2011'`
+- patients in the newer cohort: `initialEra: '2021'`
+
 ---
 
 ## Styling

package/dist/index.esm.js

@@ -6,7 +6,7 @@ import { Map, AttributionControl, Popup, VectorTileSource, GeoJSONSource } from
 function resolveEffectiveEra(nation, requestedEra) {
   switch (nation) {
     case "all":
-      return "2011";
+      return requestedEra;
     case "england":
       return requestedEra;
     case "wales":
@@ -882,6 +882,14 @@ function normalizeLeadCentreInput(data) {
     properties: { label }
   };
 }
+
+// src/overlays/mvtLayerName.ts
+var DEFAULT_TILES_SCHEMA = "public";
+function buildMvtLayerName(baseName, tier, schema = DEFAULT_TILES_SCHEMA) {
+  return `${schema}.${baseName}_${tier}`;
+}
+
+// src/overlays/localAuthority.ts
 var LOCAL_AUTHORITY_SOURCE_ID = "rcpch-imd-la-overlay";
 var LOCAL_AUTHORITY_LAYER_ID = "rcpch-imd-la-overlay-line";
 var LOCAL_AUTHORITY_TABLE_PREFIX = "la_tiles";
@@ -895,8 +903,8 @@ function addOrUpdateLocalAuthorityOverlay(map, tilesBaseUrl, style) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = localAuthoritySourceId(tier);
     const layerId = localAuthorityLayerId(tier);
-    const fullTableName = `public.${LOCAL_AUTHORITY_TABLE_PREFIX}_${tier}`;
-    const sourceLayer = `${LOCAL_AUTHORITY_TABLE_PREFIX}_${tier}`;
+    const fullTableName = buildMvtLayerName(LOCAL_AUTHORITY_TABLE_PREFIX, tier);
+    const sourceLayer = fullTableName;
     const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {
@@ -968,8 +976,8 @@ function addOrUpdateBoundaryOverlay(map, tilesBaseUrl, input) {
   for (const { tier, minzoom, maxzoom } of ZOOM_TIERS) {
     const sourceId = overlaySourceId(input.sourceId, tier);
     const layerId = overlayLayerId(input.layerId, tier);
-    const fullTableName = `public.${input.tablePrefix}_${tier}`;
-    const sourceLayer = `${input.tablePrefix}_${tier}`;
+    const fullTableName = buildMvtLayerName(input.tablePrefix, tier);
+    const sourceLayer = fullTableName;
     const tileUrl = buildTileUrl(tilesBaseUrl, fullTableName);
     const existing = map.getSource(sourceId);
     if (existing instanceof VectorTileSource) {