@defra/interactive-map 0.0.50-alpha → 0.0.51-apha

package/providers/beta/openlayers/dist/umd/index.js

@@ -1,2 +1,2 @@
 /*! For license information please see index.js.LICENSE.txt */
-!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define("defra",[],t):"object"==typeof exports?exports.defra=t():(e.defra=e.defra||{},e.defra.openLayersProvider=t())}(this,()=>(()=>{"use strict";var e,t,r={},n={};function o(e){var t=n[e];if(void 0!==t)return t.exports;var i=n[e]={exports:{}};return r[e](i,i.exports,o),i.exports}o.m=r,o.d=(e,t)=>{for(var r in t)o.o(t,r)&&!o.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},o.f={},o.e=e=>Promise.all(Object.keys(o.f).reduce((t,r)=>(o.f[r](e,t),t),[])),o.u=e=>"im-openlayers-provider.js",o.miniCssF=e=>{},o.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),o.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),e={},t="defra.openLayersProvider:",o.l=(r,n,i,a)=>{if(e[r])e[r].push(n);else{var u,c;if(void 0!==i)for(var f=document.getElementsByTagName("script"),p=0;p<f.length;p++){var s=f[p];if(s.getAttribute("src")==r||s.getAttribute("data-webpack")==t+i){u=s;break}}u||(c=!0,(u=document.createElement("script")).charset="utf-8",o.nc&&u.setAttribute("nonce",o.nc),u.setAttribute("data-webpack",t+i),u.src=r),e[r]=[n];var l=(t,n)=>{u.onerror=u.onload=null,clearTimeout(d);var o=e[r];if(delete e[r],u.parentNode&&u.parentNode.removeChild(u),o&&o.forEach(e=>e(n)),t)return t(n)},d=setTimeout(l.bind(null,void 0,{type:"timeout",target:u}),12e4);u.onerror=l.bind(null,u.onerror),u.onload=l.bind(null,u.onload),c&&document.head.appendChild(u)}},o.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},(()=>{var e;o.g.importScripts&&(e=o.g.location+"");var t=o.g.document;if(!e&&t&&(t.currentScript&&"SCRIPT"===t.currentScript.tagName.toUpperCase()&&(e=t.currentScript.src),!e)){var r=t.getElementsByTagName("script");if(r.length)for(var n=r.length-1;n>-1&&(!e||!/^http(s?):/.test(e));)e=r[n--].src}if(!e)throw new Error("Automatic publicPath is not supported in this browser");e=e.replace(/^blob:/,"").replace(/#.*$/,"").replace(/\?.*$/,"").replace(/\/[^\/]+$/,"/"),o.p=e})(),(()=>{var e={57:0};o.f.j=(t,r)=>{var n=o.o(e,t)?e[t]:void 0;if(0!==n)if(n)r.push(n[2]);else{var i=new Promise((r,o)=>n=e[t]=[r,o]);r.push(n[2]=i);var a=o.p+o.u(t),u=new Error;o.l(a,r=>{if(o.o(e,t)&&(0!==(n=e[t])&&(e[t]=void 0),n)){var i=r&&("load"===r.type?"missing":r.type),a=r&&r.target&&r.target.src;u.message="Loading chunk "+t+" failed.\n("+i+": "+a+")",u.name="ChunkLoadError",u.type=i,u.request=a,n[1](u)}},"chunk-"+t,t)}};var t=(t,r)=>{var n,i,[a,u,c]=r,f=0;if(a.some(t=>0!==e[t])){for(n in u)o.o(u,n)&&(o.m[n]=u[n]);c&&c(o)}for(t&&t(r);f<a.length;f++)i=a[f],o.o(e,i)&&e[i]&&e[i][0](),e[i]=0},r=this.webpackChunkdefra_DefraMap=this.webpackChunkdefra_DefraMap||[];r.forEach(t.bind(null,0)),r.push=t.bind(null,r.push.bind(r))})();var i={};function a(){var e,t,r="function"==typeof Symbol?Symbol:{},n=r.iterator||"@@iterator",o=r.toStringTag||"@@toStringTag";function i(r,n,o,i){var a=n&&n.prototype instanceof f?n:f,p=Object.create(a.prototype);return u(p,"_invoke",function(r,n,o){var i,a,u,f=0,p=o||[],s=!1,l={p:0,n:0,v:e,a:d,f:d.bind(e,4),d:function(t,r){return i=t,a=0,u=e,l.n=r,c}};function d(r,n){for(a=r,u=n,t=0;!s&&f&&!o&&t<p.length;t++){var o,i=p[t],d=l.p,v=i[2];r>3?(o=v===n)&&(u=i[(a=i[4])?5:(a=3,3)],i[4]=i[5]=e):i[0]<=d&&((o=r<2&&d<i[1])?(a=0,l.v=n,l.n=i[1]):d<v&&(o=r<3||i[0]>n||n>v)&&(i[4]=r,i[5]=n,l.n=v,a=0))}if(o||r>1)return c;throw s=!0,n}return function(o,p,v){if(f>1)throw TypeError("Generator is already running");for(s&&1===p&&d(p,v),a=p,u=v;(t=a<2?e:u)||!s;){i||(a?a<3?(a>1&&(l.n=-1),d(a,u)):l.n=u:l.v=u);try{if(f=2,i){if(a||(o="next"),t=i[o]){if(!(t=t.call(i,u)))throw TypeError("iterator result is not an object");if(!t.done)return t;u=t.value,a<2&&(a=0)}else 1===a&&(t=i.return)&&t.call(i),a<2&&(u=TypeError("The iterator does not provide a '"+o+"' method"),a=1);i=e}else if((t=(s=l.n<0)?u:r.call(n,l))!==c)break}catch(t){i=e,a=1,u=t}finally{f=1}}return{value:t,done:s}}}(r,o,i),!0),p}var c={};function f(){}function p(){}function s(){}t=Object.getPrototypeOf;var l=[][n]?t(t([][n]())):(u(t={},n,function(){return this}),t),d=s.prototype=f.prototype=Object.create(l);function v(e){return Object.setPrototypeOf?Object.setPrototypeOf(e,s):(e.__proto__=s,u(e,o,"GeneratorFunction")),e.prototype=Object.create(d),e}return p.prototype=s,u(d,"constructor",s),u(s,"constructor",p),p.displayName="GeneratorFunction",u(s,o,"GeneratorFunction"),u(d),u(d,o,"Generator"),u(d,n,function(){return this}),u(d,"toString",function(){return"[object Generator]"}),(a=function(){return{w:i,m:v}})()}function u(e,t,r,n){var o=Object.defineProperty;try{o({},"",{})}catch(e){o=0}u=function(e,t,r,n){function i(t,r){u(e,t,function(e){return this._invoke(t,r,e)})}t?o?o(e,t,{value:r,enumerable:!n,configurable:!n,writable:!n}):e[t]=r:(i("next",0),i("throw",1),i("return",2))},u(e,t,r,n)}function c(e,t,r,n,o,i,a){try{var u=e[i](a),c=u.value}catch(e){return void r(e)}u.done?t(c):Promise.resolve(c).then(n,o)}function f(){var e,t,r=(arguments.length>0&&void 0!==arguments[0]?arguments[0]:{}).zoomAlignment;return{checkDeviceCapabilities:function(){return{isSupported:!!document.createElement("canvas").getContext,error:"Canvas is not supported in this browser"}},load:(e=a().m(function e(){var t,n;return a().w(function(e){for(;;)switch(e.n){case 0:return e.n=1,o.e(142).then(o.bind(o,501));case 1:return t=e.v.default,n={zoomAlignment:r,crs:"EPSG:27700"},e.a(2,{MapProvider:t,mapProviderConfig:n})}},e)}),t=function(){var t=this,r=arguments;return new Promise(function(n,o){var i=e.apply(t,r);function a(e){c(i,n,o,a,u,"next",e)}function u(e){c(i,n,o,a,u,"throw",e)}a(void 0)})},function(){return t.apply(this,arguments)})}}return o.d(i,{default:()=>f}),i.default})());
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define("defra",[],t):"object"==typeof exports?exports.defra=t():(e.defra=e.defra||{},e.defra.openLayersProvider=t())}(this,()=>(()=>{"use strict";var e,t,r={},n={};function o(e){var t=n[e];if(void 0!==t)return t.exports;var i=n[e]={exports:{}};return r[e](i,i.exports,o),i.exports}o.m=r,o.d=(e,t)=>{for(var r in t)o.o(t,r)&&!o.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},o.f={},o.e=e=>Promise.all(Object.keys(o.f).reduce((t,r)=>(o.f[r](e,t),t),[])),o.u=e=>"im-openlayers-provider.js",o.miniCssF=e=>{},o.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),o.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),e={},t="defra.openLayersProvider:",o.l=(r,n,i,a)=>{if(e[r])e[r].push(n);else{var u,c;if(void 0!==i)for(var f=document.getElementsByTagName("script"),p=0;p<f.length;p++){var s=f[p];if(s.getAttribute("src")==r||s.getAttribute("data-webpack")==t+i){u=s;break}}u||(c=!0,(u=document.createElement("script")).charset="utf-8",o.nc&&u.setAttribute("nonce",o.nc),u.setAttribute("data-webpack",t+i),u.src=r),e[r]=[n];var l=(t,n)=>{u.onerror=u.onload=null,clearTimeout(d);var o=e[r];if(delete e[r],u.parentNode&&u.parentNode.removeChild(u),o&&o.forEach(e=>e(n)),t)return t(n)},d=setTimeout(l.bind(null,void 0,{type:"timeout",target:u}),12e4);u.onerror=l.bind(null,u.onerror),u.onload=l.bind(null,u.onload),c&&document.head.appendChild(u)}},o.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},(()=>{var e;o.g.importScripts&&(e=o.g.location+"");var t=o.g.document;if(!e&&t&&(t.currentScript&&"SCRIPT"===t.currentScript.tagName.toUpperCase()&&(e=t.currentScript.src),!e)){var r=t.getElementsByTagName("script");if(r.length)for(var n=r.length-1;n>-1&&(!e||!/^http(s?):/.test(e));)e=r[n--].src}if(!e)throw new Error("Automatic publicPath is not supported in this browser");e=e.replace(/^blob:/,"").replace(/#.*$/,"").replace(/\?.*$/,"").replace(/\/[^\/]+$/,"/"),o.p=e})(),(()=>{var e={57:0};o.f.j=(t,r)=>{var n=o.o(e,t)?e[t]:void 0;if(0!==n)if(n)r.push(n[2]);else{var i=new Promise((r,o)=>n=e[t]=[r,o]);r.push(n[2]=i);var a=o.p+o.u(t),u=new Error;o.l(a,r=>{if(o.o(e,t)&&(0!==(n=e[t])&&(e[t]=void 0),n)){var i=r&&("load"===r.type?"missing":r.type),a=r&&r.target&&r.target.src;u.message="Loading chunk "+t+" failed.\n("+i+": "+a+")",u.name="ChunkLoadError",u.type=i,u.request=a,n[1](u)}},"chunk-"+t,t)}};var t=(t,r)=>{var n,i,[a,u,c]=r,f=0;if(a.some(t=>0!==e[t])){for(n in u)o.o(u,n)&&(o.m[n]=u[n]);c&&c(o)}for(t&&t(r);f<a.length;f++)i=a[f],o.o(e,i)&&e[i]&&e[i][0](),e[i]=0},r=this.webpackChunkdefra_DefraMap=this.webpackChunkdefra_DefraMap||[];r.forEach(t.bind(null,0)),r.push=t.bind(null,r.push.bind(r))})();var i={};function a(){var e,t,r="function"==typeof Symbol?Symbol:{},n=r.iterator||"@@iterator",o=r.toStringTag||"@@toStringTag";function i(r,n,o,i){var a=n&&n.prototype instanceof f?n:f,p=Object.create(a.prototype);return u(p,"_invoke",function(r,n,o){var i,a,u,f=0,p=o||[],s=!1,l={p:0,n:0,v:e,a:d,f:d.bind(e,4),d:function(t,r){return i=t,a=0,u=e,l.n=r,c}};function d(r,n){for(a=r,u=n,t=0;!s&&f&&!o&&t<p.length;t++){var o,i=p[t],d=l.p,v=i[2];r>3?(o=v===n)&&(u=i[(a=i[4])?5:(a=3,3)],i[4]=i[5]=e):i[0]<=d&&((o=r<2&&d<i[1])?(a=0,l.v=n,l.n=i[1]):d<v&&(o=r<3||i[0]>n||n>v)&&(i[4]=r,i[5]=n,l.n=v,a=0))}if(o||r>1)return c;throw s=!0,n}return function(o,p,v){if(f>1)throw TypeError("Generator is already running");for(s&&1===p&&d(p,v),a=p,u=v;(t=a<2?e:u)||!s;){i||(a?a<3?(a>1&&(l.n=-1),d(a,u)):l.n=u:l.v=u);try{if(f=2,i){if(a||(o="next"),t=i[o]){if(!(t=t.call(i,u)))throw TypeError("iterator result is not an object");if(!t.done)return t;u=t.value,a<2&&(a=0)}else 1===a&&(t=i.return)&&t.call(i),a<2&&(u=TypeError("The iterator does not provide a '"+o+"' method"),a=1);i=e}else if((t=(s=l.n<0)?u:r.call(n,l))!==c)break}catch(t){i=e,a=1,u=t}finally{f=1}}return{value:t,done:s}}}(r,o,i),!0),p}var c={};function f(){}function p(){}function s(){}t=Object.getPrototypeOf;var l=[][n]?t(t([][n]())):(u(t={},n,function(){return this}),t),d=s.prototype=f.prototype=Object.create(l);function v(e){return Object.setPrototypeOf?Object.setPrototypeOf(e,s):(e.__proto__=s,u(e,o,"GeneratorFunction")),e.prototype=Object.create(d),e}return p.prototype=s,u(d,"constructor",s),u(s,"constructor",p),p.displayName="GeneratorFunction",u(s,o,"GeneratorFunction"),u(d),u(d,o,"Generator"),u(d,n,function(){return this}),u(d,"toString",function(){return"[object Generator]"}),(a=function(){return{w:i,m:v}})()}function u(e,t,r,n){var o=Object.defineProperty;try{o({},"",{})}catch(e){o=0}u=function(e,t,r,n){function i(t,r){u(e,t,function(e){return this._invoke(t,r,e)})}t?o?o(e,t,{value:r,enumerable:!n,configurable:!n,writable:!n}):e[t]=r:(i("next",0),i("throw",1),i("return",2))},u(e,t,r,n)}function c(e,t,r,n,o,i,a){try{var u=e[i](a),c=u.value}catch(e){return void r(e)}u.done?t(c):Promise.resolve(c).then(n,o)}function f(){var e,t,r=(arguments.length>0&&void 0!==arguments[0]?arguments[0]:{}).zoomAlignment;return{checkDeviceCapabilities:function(){return{isSupported:!!document.createElement("canvas").getContext,error:"Canvas is not supported in this browser"}},load:(e=a().m(function e(){var t,n;return a().w(function(e){for(;;)switch(e.n){case 0:return e.n=1,o.e(142).then(o.bind(o,382));case 1:return t=e.v.default,n={zoomAlignment:r,crs:"EPSG:27700"},e.a(2,{MapProvider:t,mapProviderConfig:n})}},e)}),t=function(){var t=this,r=arguments;return new Promise(function(n,o){var i=e.apply(t,r);function a(e){c(i,n,o,a,u,"next",e)}function u(e){c(i,n,o,a,u,"throw",e)}a(void 0)})},function(){return t.apply(this,arguments)})}}return o.d(i,{default:()=>f}),i.default})());

package/providers/beta/openlayers/src/index.js

@@ -1,14 +1,30 @@
+/**
+ * @typedef {import('../../../../src/types.js').MapProviderDescriptor} MapProviderDescriptor
+ * @typedef {import('../../../../src/types.js').MapProviderLoadResult} MapProviderLoadResult
+ * @typedef {import('../../../../src/types.js').MapProviderConfig} MapProviderConfig
+ * @typedef {import('../../../../src/types.js').OpenLayersProviderConfig} OpenLayersProviderConfig
+ */
+
+/**
+ * Creates an OpenLayers provider descriptor for lazy-loading the map provider.
+ *
+ * @param {OpenLayersProviderConfig} [config={}] - Optional provider configuration overrides.
+ * @returns {MapProviderDescriptor} The map provider descriptor.
+ */
 export default function createOpenLayersProvider ({ zoomAlignment } = {}) {
   return {
     checkDeviceCapabilities: () => ({
       isSupported: !!document.createElement('canvas').getContext,
       error: 'Canvas is not supported in this browser'
     }),
+    /** @returns {Promise<MapProviderLoadResult>} */
     load: async () => {
       const MapProvider = (await import(/* webpackChunkName: "im-openlayers-provider" */ './openlayersProvider.js')).default
 
+      /** @type {MapProviderConfig} */
       const mapProviderConfig = {
         zoomAlignment,
+        // Fixed, not user-configurable — the OpenLayers provider is BNG-native only.
         crs: 'EPSG:27700'
       }
 

package/providers/beta/openlayers/src/openlayersProvider.js

@@ -1,10 +1,13 @@
+/**
+ * @typedef {import('../../../../src/types.js').MapProvider} MapProvider
+ * @typedef {import('../../../../src/types.js').MapProviderConfig} MapProviderConfig
+ */
 import { MapProvider } from '../../../mapProvider.js'
 import OlMap from 'ol/Map.js'
 import View from 'ol/View.js'
 import { defaults as defaultInteractions } from 'ol/interaction/defaults.js'
 import { getCenter as getExtentCenter } from 'ol/extent.js'
-import proj4 from 'proj4'
-import { register } from 'ol/proj/proj4.js'
+import { BNG_CRS } from './utils/bngProjection.js'
 import { supportedShortcuts, DEFAULTS } from './defaults.js'
 import { getViewResolutionConfig, ZOOM_ALIGNMENT } from './utils/zoom.js'
 import { attachMapEvents } from './mapEvents.js'
@@ -18,7 +21,7 @@ import { applyOpenLayersFixes } from './utils/openLayersFixes.js'
 
 applyOpenLayersFixes()
 
-const CRS = 'EPSG:27700'
+const CRS = BNG_CRS
 
 const toPaddingArray = (padding) => {
   if (!padding) {
@@ -28,11 +31,18 @@ const toPaddingArray = (padding) => {
   return [top, right, bottom, left]
 }
 
-// Register British National Grid with proj4 so OL can use it
-proj4.defs(CRS, '+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m +no_defs')
-register(proj4)
-
+/**
+ * OpenLayers implementation of the MapProvider interface.
+ *
+ * @implements {MapProvider}
+ */
 export default class OpenLayersProvider extends MapProvider {
+  /**
+   * @param {Object} options - Constructor options.
+   * @param {MapProviderConfig} [options.mapProviderConfig={}] - Provider configuration.
+   * @param {Object} options.events - Event name constants.
+   * @param {Object} options.eventBus - Event emitter for publishing map events.
+   */
   constructor ({ mapProviderConfig = {}, events, eventBus }) {
     super()
     this.events = events
@@ -48,6 +58,18 @@ export default class OpenLayersProvider extends MapProvider {
     return 'OpenLayersProvider'
   }
 
+  // Unlike MapLibre, initMap() awaits the OL style/sprite fetch before constructing the map, so
+  // the base map is already loaded by the time this.map is set.
+  isBaseMapReady () {
+    return Boolean(this.map)
+  }
+
+  /**
+   * Initialize the map.
+   *
+   * @param {Object} config - Map initialization configuration.
+   * @returns {Promise<void>}
+   */
   async initMap (config) {
     const { container, padding, mapStyle, mapSize, center, zoom, bounds, minZoom, maxZoom, transformRequest, pixelRatio } = config
     this.mapStyleId = mapStyle?.id
@@ -118,6 +140,7 @@ export default class OpenLayersProvider extends MapProvider {
     })
   }
 
+  /** Destroy the map and clean up resources. */
   destroyMap () {
     this.mapEventHandles?.remove()
     this.appEventHandles?.remove()
@@ -141,6 +164,13 @@ export default class OpenLayersProvider extends MapProvider {
   // Side-effects
   // ==========================
 
+  /**
+   * Set map view with optional center and zoom.
+   *
+   * @param {Object} options - View options.
+   * @param {[number, number]} [options.center] - Center coordinates [easting, northing].
+   * @param {number} [options.zoom] - Zoom level.
+   */
   setView ({ center, zoom }) {
     this.view.animate({
       center: center ?? this.view.getCenter(),
@@ -149,6 +179,11 @@ export default class OpenLayersProvider extends MapProvider {
     })
   }
 
+  /**
+   * Zoom in by delta.
+   *
+   * @param {number} zoomDelta - Amount to zoom in.
+   */
   zoomIn (zoomDelta) {
     this.view.animate({
       zoom: this.view.getZoom() + zoomDelta,
@@ -156,6 +191,11 @@ export default class OpenLayersProvider extends MapProvider {
     })
   }
 
+  /**
+   * Zoom out by delta.
+   *
+   * @param {number} zoomDelta - Amount to zoom out.
+   */
   zoomOut (zoomDelta) {
     this.view.animate({
       zoom: this.view.getZoom() - zoomDelta,
@@ -163,6 +203,11 @@ export default class OpenLayersProvider extends MapProvider {
     })
   }
 
+  /**
+   * Pan map by pixel offset [x, y]. Positive x pans right, positive y pans down.
+   *
+   * @param {[number, number]} offset - Pixel offset [x, y].
+   */
   panBy (offset) {
     const center = this.view.getCenter()
     const resolution = this.view.getResolution()
@@ -173,11 +218,21 @@ export default class OpenLayersProvider extends MapProvider {
     })
   }
 
+  /**
+   * Fit map view to the specified bounds or GeoJSON geometry.
+   *
+   * @param {[number, number, number, number] | object} bounds - Bounds as [west, south, east, north] (BNG easting/northing), or a GeoJSON Feature, FeatureCollection, or geometry.
+   */
   fitToBounds (bounds) {
     const extent = Array.isArray(bounds) ? bounds : getExtentFromGeoJSON(bounds)
     this.view.fit(extent, { duration: DEFAULTS.animationDuration })
   }
 
+  /**
+   * Set map padding as pixel insets from the top, bottom, left and right edges of the map.
+   *
+   * @param {{ top?: number, bottom?: number, left?: number, right?: number }} padding - Padding in pixels.
+   */
   setPadding (padding) {
     this.view.padding = toPaddingArray(padding)
   }
@@ -186,6 +241,11 @@ export default class OpenLayersProvider extends MapProvider {
   // Read-only getters
   // ==========================
 
+  /**
+   * Get current center coordinates [easting, northing].
+   *
+   * @returns {[number, number]}
+   */
   getCenter () {
     const center = this.view.getCenter()
     const p = DEFAULTS.coordinatePrecision
@@ -195,19 +255,47 @@ export default class OpenLayersProvider extends MapProvider {
     ]
   }
 
+  /**
+   * Get current zoom level.
+   *
+   * @returns {number}
+   */
   getZoom () {
     return this.view.getZoom()
   }
 
+  /**
+   * Get current bounds as [west, south, east, north] (BNG easting/northing).
+   *
+   * @returns {[number, number, number, number]}
+   */
   getBounds () {
     const extent = this.view.calculateExtent(this.map.getSize())
     return extent.map(n => Math.round(n * 100) / 100)
   }
 
+  /**
+   * Query rendered features at a screen pixel position (x from left edge, y from top edge of viewport).
+   *
+   * @param {{ x: number, y: number }} point - Screen pixel position.
+   * @param {Object} [options]
+   * @param {number} [options.radius] - Pixel radius to expand the query area. Results sorted closest-first.
+   * @returns {any[]}
+   */
   getFeaturesAtPoint (point, options) {
     return queryFeatures(this.map, point, options)
   }
 
+  /**
+   * Get a feature's full geometry, stitched from its vector-tile fragments. A feature that
+   * spans multiple tiles is otherwise only visible as whichever single fragment was clicked —
+   * this combines every loaded fragment sharing the same id into one Polygon/MultiPolygon.
+   *
+   * @param {string} layerId
+   * @param {string|number} featureId
+   * @param {string} [idProperty] - Feature property to match on, if not using the tile's native feature id.
+   * @returns {object|null} A GeoJSON Polygon or MultiPolygon geometry, or null if no fragments were found.
+   */
   getFeatureGeometry (layerId, featureId, idProperty) {
     const fragments = collectTileFragments(this.map, layerId, featureId, idProperty)
     if (fragments.length === 0) { return null }
@@ -216,6 +304,12 @@ export default class OpenLayersProvider extends MapProvider {
     return { type: 'MultiPolygon', coordinates: coords }
   }
 
+  /**
+   * Set pointer cursor on the map canvas when hovering over any of the given layer IDs.
+   * Call with an empty array to remove all hover cursor listeners.
+   *
+   * @param {string[]} layerIds
+   */
   setHoverCursor (layerIds) {
     if (!this.map) {
       return
@@ -223,15 +317,38 @@ export default class OpenLayersProvider extends MapProvider {
     this._onHoverMove = setupHoverCursor(this.map, layerIds, this._onHoverMove)
   }
 
+  /**
+   * Get every currently rendered feature across the given layer IDs (not scoped to a point or
+   * area, unlike getFeaturesAtPoint).
+   *
+   * @param {string[]} layerIds
+   * @returns {any[]}
+   */
   getVisibleFeatures (layerIds) {
     return getVisibleFeatures(this.map, layerIds)
   }
 
+  /**
+   * @experimental Update highlighted features on the map. Remembers its arguments (see
+   * reapplyHighlights) since, unlike MapLibre, a basemap style change here swaps in a fresh
+   * base layer/source that highlights must be explicitly re-applied against.
+   *
+   * @param {any[]} selectedFeatures - Features to highlight.
+   * @param {any} activeFeatures - Features to highlight with the keyboard cursor ring.
+   * @param {any} stylesMap - Style configuration for highlighting.
+   * @returns {any}
+   */
   updateHighlightedFeatures (selectedFeatures, activeFeatures, stylesMap) {
     this._lastHighlightArgs = { selectedFeatures, activeFeatures, stylesMap }
     return updateHighlightedFeatures(this.map, selectedFeatures, activeFeatures, stylesMap)
   }
 
+  /**
+   * Re-applies the last updateHighlightedFeatures call. Called after a basemap style change
+   * (see appEvents.js's handleSetMapStyle) — MAP_DATA_CHANGE won't fire for the new base
+   * layer's source, so highlights would otherwise be lost silently until the next selection
+   * change.
+   */
   reapplyHighlights () {
     if (!this._lastHighlightArgs) {
       return
@@ -244,18 +361,41 @@ export default class OpenLayersProvider extends MapProvider {
   // Spatial helpers
   // ==========================
 
+  /**
+   * Get the dimensions of the visible map area as a formatted string (e.g., '400m by 750m').
+   *
+   * @returns {string}
+   */
   getAreaDimensions () {
     return getAreaDimensions(getPaddedExtent(this.map))
   }
 
+  /**
+   * Get cardinal direction and distance between two coordinates [easting, northing]. Returns a formatted string (e.g., 'north 400m' or 'south 400m, west 750m').
+   *
+   * @param {[number, number]} from - Start coordinates [easting, northing].
+   * @param {[number, number]} to - End coordinates [easting, northing].
+   * @returns {string}
+   */
   getCardinalMove (from, to) {
     return getCardinalMove(from, to)
   }
 
+  /**
+   * Get map resolution in metres per pixel.
+   *
+   * @returns {number}
+   */
   getResolution () {
     return this.view.getResolution()
   }
 
+  /**
+   * Convert map coordinates [easting, northing] to screen pixel position (x from left edge, y from top edge of viewport).
+   *
+   * @param {[number, number]} coords - Map coordinates [easting, northing].
+   * @returns {{ x: number, y: number }} Screen pixel position.
+   */
   mapToScreen (coords) {
     if (!this.map) {
       return { x: 0, y: 0 }
@@ -267,10 +407,23 @@ export default class OpenLayersProvider extends MapProvider {
     return { x: pixel[0], y: pixel[1] }
   }
 
+  /**
+   * Convert screen pixel position (x from left edge, y from top edge of viewport) to map coordinates [easting, northing].
+   *
+   * @param {{ x: number, y: number }} point - Screen pixel position.
+   * @returns {[number, number]} Map coordinates [easting, northing].
+   */
   screenToMap (point) {
     return this.map.getCoordinateFromPixel([point.x, point.y])
   }
 
+  /**
+   * Returns true if the geometry's screen bounding box overlaps the given panel rectangle.
+   *
+   * @param {object} geojson - GeoJSON Feature, FeatureCollection, or geometry.
+   * @param {DOMRect} panelRect - Bounding rect of the panel element (viewport coordinates).
+   * @returns {boolean}
+   */
   isGeometryObscured (geojson, panelRect) {
     return isGeometryObscured(geojson, panelRect, this.map)
   }

package/providers/beta/openlayers/src/openlayersProvider.test.js

@@ -127,6 +127,19 @@ describe('OpenLayersProvider', () => {
     })
   })
 
+  describe('isBaseMapReady', () => {
+    it('returns false before initMap has run', () => {
+      const { provider } = makeProvider()
+      expect(provider.isBaseMapReady()).toBe(false)
+    })
+
+    it('returns true once initMap has set this.map', async () => {
+      const { provider } = makeProvider()
+      await provider.initMap(defaultInitConfig)
+      expect(provider.isBaseMapReady()).toBe(true)
+    })
+  })
+
   describe('initMap', () => {
     it('creates vector tile layer, OL objects, and emits MAP_READY by default', async () => {
       const { provider, eventBus } = makeProvider()

package/providers/beta/openlayers/src/utils/bngProjection.js

@@ -0,0 +1,9 @@
+import proj4 from 'proj4'
+import { register } from 'ol/proj/proj4.js'
+
+export const BNG_CRS = 'EPSG:27700'
+
+// Registers British National Grid with proj4 so OL can use it — shared so callers don't
+// duplicate the proj4.defs() string.
+proj4.defs(BNG_CRS, '+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m +no_defs')
+register(proj4)

package/providers/beta/openlayers/src/utils/filterEvaluator.js

@@ -0,0 +1,32 @@
+import { buildExpression, newEvaluationContext } from 'ol/expr/cpu.js'
+import { BooleanType, newParsingContext } from 'ol/expr/expression.js'
+
+/**
+ * Compiles a Mapbox-style filter expression (get/in/literal/to-string/all/! — the same shape
+ * Dataset.filter produces, see plugins/datasets/src/registry/dataset.js) into a reusable
+ * per-feature predicate. Shared by two consumers with very different call frequencies:
+ * canvasPatternStyle.js's style function (evaluated once per feature on every render pass, for
+ * every pattern-filtered sublayer sharing a source) and queryFeatures.js's getVisibleFeatures
+ * (evaluated on demand, only when reading straight off a shared vector-tile/vector source).
+ *
+ * The evaluation context is built once here and mutated on every call rather than allocated
+ * fresh per feature — confirmed against ol/expr/cpu.js's own compiled evaluators, which only
+ * ever read context.properties/featureId/geometryType/resolution/variables synchronously within
+ * the call and never retain a reference, so reuse is safe. None of the expressions this
+ * evaluates touch resolution/variables, so nothing else needs resetting between features.
+ * @param {Array|undefined} filter
+ * @returns {(function(import('ol/Feature.js').default): boolean)|null}
+ */
+export const buildFilterEvaluator = (filter) => {
+  if (!filter) {
+    return null
+  }
+  const evaluator = buildExpression(filter, BooleanType, newParsingContext())
+  const context = newEvaluationContext()
+  return (feature) => {
+    context.properties = feature.getProperties()
+    context.featureId = feature.getId() ?? null
+    context.geometryType = feature.getGeometry()?.getType() ?? ''
+    return Boolean(evaluator(context))
+  }
+}

package/providers/beta/openlayers/src/utils/filterEvaluator.test.js

@@ -0,0 +1,36 @@
+import Feature from 'ol/Feature.js'
+import Point from 'ol/geom/Point.js'
+import { buildFilterEvaluator } from './filterEvaluator.js'
+
+const feature = (props) => new Feature({ geometry: new Point([0, 0]), ...props })
+
+describe('buildFilterEvaluator', () => {
+  it('returns null for no filter', () => {
+    expect(buildFilterEvaluator(undefined)).toBeNull()
+  })
+
+  it('matches a feature whose property satisfies the filter', () => {
+    const matches = buildFilterEvaluator(['==', ['get', 'category'], 'a'])
+    expect(matches(feature({ category: 'a' }))).toBe(true)
+  })
+
+  it('rejects a feature whose property does not satisfy the filter', () => {
+    const matches = buildFilterEvaluator(['==', ['get', 'category'], 'a'])
+    expect(matches(feature({ category: 'b' }))).toBe(false)
+  })
+
+  it('evaluates correctly for a feature with no geometry', () => {
+    const matches = buildFilterEvaluator(['==', ['get', 'category'], 'a'])
+    expect(matches(new Feature({ category: 'a' }))).toBe(true)
+  })
+
+  it('reuses one evaluation context across many features without leaking state between them', () => {
+    const matches = buildFilterEvaluator(['==', ['get', 'category'], 'a'])
+    const results = [
+      matches(feature({ category: 'a' })),
+      matches(feature({ category: 'b' })),
+      matches(feature({ category: 'a' }))
+    ]
+    expect(results).toEqual([true, false, true])
+  })
+})

package/providers/beta/openlayers/src/utils/highlightFeatures.js

@@ -7,7 +7,7 @@ import Stroke from 'ol/style/Stroke.js'
 import Fill from 'ol/style/Fill.js'
 import Icon from 'ol/style/Icon.js'
 import { collectTileFragments } from './vtTileFragments.js'
-import { getCachedSymbolImage } from './symbolImages.js'
+import { getCachedSymbolImage, getActiveSymbolImageId, getSelectedSymbolImageId, SYMBOL_RASTER_PIXEL_RATIO } from './symbolImages.js'
 import { symbolRegistry } from '../../../../../src/services/symbolRegistry.js'
 import { getSymbolAnchor } from '../../../../../src/utils/symbolUtils.js'
 
@@ -108,14 +108,19 @@ const wrapVtLayers = (map, selectedKeys, activeKeys, idPropsMap, stylesMap) => {
       return
     }
 
-    if (!layer._highlightOriginalStyle) {
+    // A restyle made directly via layer.setStyle() while a selection stays active (e.g. a
+    // theme switch) replaces our wrap with a fresh style function — comparing against our own
+    // last-installed wrap detects this and re-captures the new live style instead of going stale.
+    if (!layer._highlightOriginalStyle || layer.getStyleFunction() !== layer._highlightWrappedStyle) {
       layer._highlightOriginalStyle = layer.getStyleFunction()
     }
     const orig = layer._highlightOriginalStyle
 
-    layer.setStyle((feature, resolution) => {
+    const wrappedStyle = (feature, resolution) => {
       const base = orig(feature, resolution)
-      const styleLayerId = feature.get('mapbox-layer')?.id
+      // draw-ol's MVT tiles carry a 'mapbox-layer' object; tiles-backed datasets tag the OL
+      // layer itself with 'layerId' instead.
+      const styleLayerId = feature.get('mapbox-layer')?.id ?? layer.get('layerId')
       if (!styleLayerId) {
         return base
       }
@@ -136,7 +141,9 @@ const wrapVtLayers = (map, selectedKeys, activeKeys, idPropsMap, stylesMap) => {
       }
 
       return [...toStyleArray(base), ...highlightStyles]
-    })
+    }
+    layer._highlightWrappedStyle = wrappedStyle
+    layer.setStyle(wrappedStyle)
     // setStyle() calls layer.changed() internally — no source.changed() needed
     // (source.changed() works but causes a visible flicker on selection)
   })
@@ -149,12 +156,7 @@ const wrapVtLayers = (map, selectedKeys, activeKeys, idPropsMap, stylesMap) => {
 // ---------------------------------------------------------------------------
 
 const getOrCreateHighlightLayer = (map) => {
-  let layer = null
-  map.getLayers().forEach(l => {
-    if (l.get(HIGHLIGHT_MARKER)) {
-      layer = l
-    }
-  })
+  let layer = map.getLayers().getArray().find(mapLayer => mapLayer.get(HIGHLIGHT_MARKER))
   if (!layer) {
     layer = new VectorLayer({ source: new VectorSource(), zIndex: HIGHLIGHT_Z + 2 })
     layer.set(HIGHLIGHT_MARKER, true)
@@ -164,6 +166,11 @@ const getOrCreateHighlightLayer = (map) => {
   return layer
 }
 
+const findVectorLayer = (map, layerId) =>
+  map.getLayers().getArray().find(mapLayer =>
+    mapLayer.get('layerType') === 'vector' && !mapLayer.get(HIGHLIGHT_MARKER) && mapLayer.get('layerId') === layerId
+  )
+
 // interact's selectedFeatures carry a `properties` snapshot taken at selection time, which
 // goes stale for the symbol icon path once a map style change re-resolves the point's image
 // ids — reading straight off the live feature avoids showing the previous theme's variant.
@@ -171,17 +178,23 @@ const getLiveProperties = (map, layerId, featureId) => {
   if (featureId == null) {
     return undefined
   }
-  let properties
-  map.getLayers().forEach(l => {
-    if (properties || l.get('layerType') !== 'vector' || l.get(HIGHLIGHT_MARKER) || l.get('layerId') !== layerId) {
-      return
-    }
-    const feature = l.getSource()?.getFeatureById(String(featureId))
-    if (feature) {
-      properties = feature.getProperties()
-    }
-  })
-  return properties
+  const feature = findVectorLayer(map, layerId)?.getSource()?.getFeatureById(String(featureId))
+  return feature?.getProperties()
+}
+
+// A dataset symbol point (unlike a drawn one) has no active/selected id of its own — every
+// feature in the layer shares one base imageId, so the variant is resolved from that instead.
+const buildDatasetSymbolHighlightStyle = (map, layerId, isActive) => {
+  const symbolMeta = findVectorLayer(map, layerId)?.get('symbolMeta')
+  if (!symbolMeta) {
+    return null
+  }
+  const targetId = isActive ? getActiveSymbolImageId(symbolMeta.imageId) : getSelectedSymbolImageId(symbolMeta.imageId)
+  const canvas = targetId && getCachedSymbolImage(targetId)
+  if (!canvas) {
+    return null
+  }
+  return [new Style({ image: new Icon({ img: canvas, anchor: symbolMeta.anchor, scale: 1 / SYMBOL_RASTER_PIXEL_RATIO }), zIndex: HIGHLIGHT_Z })]
 }
 
 const addVectorHighlights = (map, source, features, isActive, stylesMap) => {
@@ -190,7 +203,9 @@ const addVectorHighlights = (map, source, features, isActive, stylesMap) => {
       continue
     }
     const liveProperties = getLiveProperties(map, layerId, featureId)
-    const styles = buildSymbolHighlightStyle(liveProperties, isActive) ?? buildHighlightStyles(stylesMap?.[layerId], isActive)
+    const styles = buildSymbolHighlightStyle(liveProperties, isActive) ??
+      buildDatasetSymbolHighlightStyle(map, layerId, isActive) ??
+      buildHighlightStyles(stylesMap?.[layerId], isActive)
     if (styles.length) {
       const olFeature = new Feature({ geometry: geoJsonFormat.readGeometry(geometry) })
       olFeature.setStyle(styles)