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

package/plugins/datasets/src/adapters/openlayers/layerBuilders.js

@@ -0,0 +1,205 @@
+import VectorSource from 'ol/source/Vector.js'
+import VectorLayer from 'ol/layer/Vector.js'
+import VectorTileSource from 'ol/source/VectorTile.js'
+import VectorTileLayer from 'ol/layer/VectorTile.js'
+import GeoJSON from 'ol/format/GeoJSON.js'
+import MVT from 'ol/format/MVT.js'
+import Feature from 'ol/Feature.js'
+import TileGrid from 'ol/tilegrid/TileGrid.js'
+import { logger } from '../../../../../src/services/logger.js'
+import { BNG_CRS } from '../../../../../providers/beta/openlayers/src/utils/bngProjection.js'
+import { buildCanvasPatternStyle } from './canvasPatternStyle.js'
+
+// Data and map both use BNG, so no coordinate transformation is needed. Importing bngProjection.js
+// (rather than just the string) also registers EPSG:27700 with proj4/OL, needed for
+// VectorTileSource's projection option below to resolve to a real projection.
+const PROJECTION = BNG_CRS
+const format = new GeoJSON({ dataProjection: PROJECTION, featureProjection: PROJECTION })
+
+// The Mapbox style spec's minzoom/maxzoom are inclusive-min, exclusive-max; OL's own semantics
+// are the exact opposite (exclusive-min, inclusive-max — see ol/layer/Layer.js's visibility
+// check). Passing registryDataset.minZoom/maxZoom straight through was a real bug: every dataset
+// at the shared default minZoom:6 vanished exactly at the map's own minZoom:6. Shifting both
+// bounds down by a tiny epsilon reproduces the Mapbox-style semantics using OL's opposite sense.
+const ZOOM_EPSILON = 1e-6
+const toOlMinZoom = (minZoom) => (minZoom === undefined ? undefined : minZoom - ZOOM_EPSILON)
+const toOlMaxZoom = (maxZoom) => (maxZoom === undefined ? undefined : maxZoom - ZOOM_EPSILON)
+
+// Symbol (icon) layers always render above fill/stroke layers, regardless of add/remove order —
+// mirrors MapLibreLayerAdapter's _maintainSymbolOrdering, but OL's zIndex sorting achieves the
+// same guarantee with no imperative re-ordering step needed.
+const SYMBOL_Z_INDEX = 1
+const DEFAULT_Z_INDEX = 0
+
+// Must stay in sync with the ST_MakeEnvelope(0, 0, 1300000, 1300000, 27700) bounds hardcoded in
+// the farming-tiles server's own vector tile sources — a wrong tile grid silently misplaces or
+// fails to load every tile. Independent of the ArcGIS-hosted OSGB36 tiles used elsewhere, which
+// use a different origin/resolution/tileSize despite sharing the same EPSG:27700 projection.
+const BNG_TILE_GRID_SIZE = 1300000
+const BNG_TILE_GRID_EXTENT = [0, 0, BNG_TILE_GRID_SIZE, BNG_TILE_GRID_SIZE]
+const BNG_TILE_SIZE = 256
+const BNG_TILE_GRID = new TileGrid({
+  extent: BNG_TILE_GRID_EXTENT,
+  origin: [BNG_TILE_GRID_EXTENT[0], BNG_TILE_GRID_EXTENT[3]], // NOSONAR: bbox [west, south, east, north] coords
+  resolutions: Array.from({ length: 25 }, (_, zoom) => (BNG_TILE_GRID_EXTENT[2] - BNG_TILE_GRID_EXTENT[0]) / (BNG_TILE_SIZE * 2 ** zoom)), // NOSONAR: bbox coords
+  tileSize: BNG_TILE_SIZE
+})
+
+/**
+ * Reads GeoJSON into OL Features, promoting idProperty onto each feature's id first —
+ * ol/format/GeoJSON has no "promoteId" source option like MapLibre's, so a property can only
+ * become the feature's id by rewriting the raw GeoJSON before it's parsed.
+ * @param {Object} geojson - a GeoJSON FeatureCollection
+ * @param {string|null} idProperty
+ * @returns {import('ol/Feature.js').default[]}
+ */
+export const readGeoJSONFeatures = (geojson, idProperty) => {
+  if (!idProperty) {
+    return format.readFeatures(geojson)
+  }
+  const withPromotedIds = {
+    ...geojson,
+    features: geojson.features.map(feature => ({ ...feature, id: feature.properties?.[idProperty] ?? feature.id }))
+  }
+  return format.readFeatures(withPromotedIds)
+}
+
+/**
+ * Fetch a geojson URL once and populate the given source — the OL equivalent of MapLibre's
+ * native one-time fetch-on-load for a geojson source whose `data` is a URL string.
+ * Fire-and-forget: the source is returned empty and populated when the fetch resolves, the
+ * same "empty now, filled in later" shape dynamic sources already use via setData.
+ * @param {import('ol/source/Vector.js').default} olSource
+ * @param {string} url
+ * @param {string|null} idProperty
+ * @param {string} datasetId - for the warning message only
+ */
+const populateFromUrl = (olSource, url, idProperty, datasetId) => {
+  fetch(url)
+    .then(response => {
+      if (!response.ok) {
+        throw new Error(`${response.status} ${response.statusText}`)
+      }
+      return response.json()
+    })
+    .then(geojson => olSource.addFeatures(readGeoJSONFeatures(geojson, idProperty)))
+    .catch(error => logger.warn(`OpenLayers datasets adapter: failed to fetch geojson for dataset "${datasetId}" — ${error.message}`))
+}
+
+/**
+ * Build the OL source for a dataset — a plain VectorSource for geojson/dynamicGeoJSON, or a
+ * VectorTileSource (BNG-native tile grid, see BNG_TILE_GRID) for a tiles-backed dataset. Several
+ * top-level datasets can point at the same tiles URL with different sourceLayer values (mirroring
+ * MapLibre's own multiple-paint-layers-per-vector-source model, e.g. existing-fields/hedge-control
+ * both reading field_parcels_with_hedges_*) — registryDataset.sourceId is already hashed from the
+ * tiles URL (see Dataset.sourceId), so the adapter's source cache naturally shares one
+ * VectorTileSource between them; only the per-layer style/filter (see OpenLayersDataset.filter)
+ * distinguishes which sourceLayer each one actually renders.
+ * @param {Object} registryDataset - an OpenLayersDataset
+ * @returns {import('ol/source/Vector.js').default|import('ol/source/VectorTile.js').default|null}
+ */
+export const createDatasetSource = (registryDataset) => {
+  const { source, id, idStrategy } = registryDataset
+  if (!source) {
+    return null
+  }
+  if (source.type === 'geojson') {
+    const olSource = new VectorSource()
+    if (typeof source.data === 'string') {
+      populateFromUrl(olSource, source.data, idStrategy, id)
+    } else if (source.data?.features?.length) {
+      olSource.addFeatures(readGeoJSONFeatures(source.data, idStrategy))
+    } else {
+      // dynamicGeoJSON sources start empty and are populated later via setData
+    }
+    return olSource
+  }
+  if (source.type === 'vector') {
+    // tiles is accepted as either a single URL string or an array (MapLibre-style) elsewhere in
+    // this codebase — see Dataset.sourceId's own Array.isArray check — but VectorTileSource's
+    // urls option requires a real array.
+    const urls = Array.isArray(source.tiles) ? source.tiles : [source.tiles]
+    return new VectorTileSource({
+      // A real ol/Feature (not MVT's default RenderFeature) — needed so canvasPatternStyle.js's
+      // filter evaluator can call feature.getGeometry()/getProperties() the same way it does for
+      // GeoJSON-backed features, and so getFeaturesInExtent-style consumers work uniformly.
+      format: new MVT({ featureClass: Feature, idProperty: idStrategy || undefined }),
+      urls,
+      projection: PROJECTION,
+      tileGrid: BNG_TILE_GRID
+    })
+  }
+  logger.warn(`OpenLayers datasets adapter: unsupported source type "${source.type}" (dataset "${id}")`)
+  return null
+}
+
+/**
+ * The style value to hand to layer.setStyle()/the layer constructor: registryDataset's own
+ * flatStyle, except for a pattern fill, which needs the genuinely crisp, CanvasPattern-based
+ * style function from canvasPatternStyle.js instead — see that module's doc for why flat-style's
+ * fill-pattern-src can't achieve this.
+ * @param {Object} registryDataset - an OpenLayersDataset
+ * @param {{ mapStyleId: string, pixelRatio: number, patternRegistry: Object }} context
+ * @returns {Object|Array<Object>|import('ol/style/Style.js').StyleFunction}
+ */
+export const resolveLayerStyle = (registryDataset, { mapStyleId, pixelRatio, patternRegistry } = {}) => {
+  if (registryDataset.hasPattern) {
+    return buildCanvasPatternStyle(registryDataset, mapStyleId, pixelRatio, patternRegistry)
+  }
+  return registryDataset.flatStyle
+}
+
+/**
+ * Build the OL layer for a dataset, wired to the given source — a Canvas VectorTileLayer for a
+ * tiles-backed dataset, or a Canvas VectorLayer otherwise. For canvas patterns, also picks the
+ * style pipeline (see resolveLayerStyle).
+ * @param {Object} registryDataset - an OpenLayersDataset
+ * @param {import('ol/source/Vector.js').default} olSource
+ * @param {{ mapStyleId: string, pixelRatio: number, patternRegistry: Object }} context
+ * @returns {import('ol/layer/Layer.js').default}
+ */
+export const createDatasetLayer = (registryDataset, olSource, context) => {
+  const isTileSource = olSource instanceof VectorTileSource
+  const LayerClass = isTileSource ? VectorTileLayer : VectorLayer
+  const layer = new LayerClass({
+    source: olSource,
+    style: resolveLayerStyle(registryDataset, context),
+    opacity: registryDataset.opacity,
+    visible: registryDataset.visibility === 'visible',
+    // See toOlMinZoom/toOlMaxZoom's comment: compensates OL's opposite inclusive/exclusive
+    // sense at each boundary, to match MapLibre's minzoom/maxzoom (which registryDataset.
+    // minZoom/maxZoom mirror) exactly.
+    minZoom: toOlMinZoom(registryDataset.minZoom),
+    maxZoom: toOlMaxZoom(registryDataset.maxZoom),
+    zIndex: registryDataset.hasSymbol ? SYMBOL_Z_INDEX : DEFAULT_Z_INDEX,
+    // ol/layer/VectorTile defaults to 'hybrid' (fills/strokes rasterised to an image tile,
+    // redrawn only on tile load — cheaper, but visibly stale/blurry while panning/zooming
+    // between loads). 'vector' re-renders true vector geometry every frame instead, matching
+    // MapLibre's own always-vector tile rendering.
+    ...(isTileSource ? { renderMode: 'vector' } : {})
+  })
+  // Required for the OL provider's queryFeatures/getVisibleFeatures (click-to-select, hover,
+  // the interact plugin's Features list) to recognise this layer at all — untagged layers are
+  // silently skipped there. 'layerId' must equal the (sub)dataset id so it matches what
+  // interactPlugin's own layerId config is written against, same convention as MapLibre.
+  // 'vectorTile' here is deliberately the *same* tag draw-ol's basemap MVT tiles use, but with a
+  // different feature shape (a real ol/Feature carrying this dataset's own sourceLayer/id, not a
+  // RenderFeature carrying a MapLibre-style 'mapbox-layer' object) — see queryFeatures.js, which
+  // branches on which shape it's actually looking at.
+  layer.set('layerType', isTileSource ? 'vectorTile' : 'vector')
+  layer.set('layerId', registryDataset.id)
+  // Sibling sublayers of the same parent share one OL source (see createDatasetSource's doc) —
+  // the *style* only actually paints/hit-tests each sublayer's own filtered subset, but
+  // queryFeatures.js's getVisibleFeatures reads straight off the shared source/tiles with no
+  // rendering step involved, so it needs this same filter to know which features are actually
+  // this sublayer's own, not just every feature the source happens to hold.
+  if (registryDataset.filter) {
+    layer.set('filter', registryDataset.filter)
+  }
+  // Lets highlightFeatures.js build a select/active highlight for a dataset symbol point —
+  // see OpenLayersDataset.symbolMeta's doc.
+  if (registryDataset.hasSymbol) {
+    layer.set('symbolMeta', registryDataset.symbolMeta)
+  }
+  return layer
+}

package/plugins/datasets/src/adapters/openlayers/layerBuilders.test.js

@@ -0,0 +1,233 @@
+import VectorSource from 'ol/source/Vector.js'
+import VectorLayer from 'ol/layer/Vector.js'
+import VectorTileSource from 'ol/source/VectorTile.js'
+import VectorTileLayer from 'ol/layer/VectorTile.js'
+import { createDatasetSource, createDatasetLayer, readGeoJSONFeatures } from './layerBuilders.js'
+import { logger } from '../../../../../src/services/logger.js'
+
+jest.mock('../../../../../src/services/logger.js', () => ({ logger: { warn: jest.fn() } }))
+
+const point = (id, coords, properties = {}) => ({
+  type: 'Feature', id, properties, geometry: { type: 'Point', coordinates: coords }
+})
+
+describe('readGeoJSONFeatures', () => {
+  it('reads features using their native id when no idProperty is given', () => {
+    const geojson = { type: 'FeatureCollection', features: [point(1, [0, 0])] }
+    const [feature] = readGeoJSONFeatures(geojson, null)
+    expect(feature.getId()).toBe(1)
+  })
+
+  it('promotes idProperty onto the feature id when given', () => {
+    const geojson = { type: 'FeatureCollection', features: [point('native-1', [0, 0], { ref: 'abc' })] }
+    const [feature] = readGeoJSONFeatures(geojson, 'ref')
+    expect(feature.getId()).toBe('abc')
+  })
+})
+
+describe('createDatasetSource', () => {
+  it('returns null when the dataset has no source', () => {
+    expect(createDatasetSource({ id: 'ds', source: null })).toBeNull()
+  })
+
+  it('builds a populated VectorSource for a geojson dataset', () => {
+    const registryDataset = {
+      id: 'ds',
+      idStrategy: null,
+      source: { type: 'geojson', data: { type: 'FeatureCollection', features: [point(1, [0, 0])] } }
+    }
+    const source = createDatasetSource(registryDataset)
+    expect(source).toBeInstanceOf(VectorSource)
+    expect(source.getFeatures()).toHaveLength(1)
+  })
+
+  it('builds an empty VectorSource for a geojson dataset with no features', () => {
+    const registryDataset = { id: 'ds', idStrategy: null, source: { type: 'geojson', data: { type: 'FeatureCollection', features: [] } } }
+    const source = createDatasetSource(registryDataset)
+    expect(source.getFeatures()).toHaveLength(0)
+  })
+
+  describe('vector tile source', () => {
+    it('builds a VectorTileSource for a tiles array', () => {
+      const registryDataset = { id: 'ds-tiles', idStrategy: null, source: { type: 'vector', tiles: ['https://example.com/{z}/{x}/{y}'] } }
+      const source = createDatasetSource(registryDataset)
+      expect(source).toBeInstanceOf(VectorTileSource)
+      expect(source.getUrls()).toEqual(['https://example.com/{z}/{x}/{y}'])
+    })
+
+    it('normalises a single tiles URL string into an array', () => {
+      const registryDataset = { id: 'ds-tiles', idStrategy: null, source: { type: 'vector', tiles: 'https://example.com/{z}/{x}/{y}' } }
+      const source = createDatasetSource(registryDataset)
+      expect(source.getUrls()).toEqual(['https://example.com/{z}/{x}/{y}'])
+    })
+
+    it('uses the fixed BNG tile grid, not the default Web Mercator one', () => {
+      const registryDataset = { id: 'ds-tiles', idStrategy: null, source: { type: 'vector', tiles: ['https://example.com/{z}/{x}/{y}'] } }
+      const source = createDatasetSource(registryDataset)
+      const tileGrid = source.getTileGrid()
+      expect(tileGrid.getExtent()).toEqual([0, 0, 1300000, 1300000])
+      expect(tileGrid.getOrigin(0)).toEqual([0, 1300000])
+      expect(tileGrid.getTileSize(0)).toBe(256)
+    })
+  })
+
+  it('warns and returns null for an unsupported source type', () => {
+    const registryDataset = { id: 'ds-unsupported', source: { type: 'raster' } }
+    expect(createDatasetSource(registryDataset)).toBeNull()
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('ds-unsupported'))
+  })
+
+  describe('geojson as a URL string', () => {
+    const flushMicrotasks = () => Promise.resolve().then(() => Promise.resolve())
+
+    beforeEach(() => {
+      global.fetch = jest.fn()
+    })
+
+    it('returns an empty source immediately, then populates it once the fetch resolves', async () => {
+      global.fetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ type: 'FeatureCollection', features: [point(1, [0, 0])] })
+      })
+      const registryDataset = { id: 'ds', idStrategy: null, source: { type: 'geojson', data: 'https://example.com/data.geojson' } }
+
+      const source = createDatasetSource(registryDataset)
+      expect(source.getFeatures()).toHaveLength(0)
+
+      await flushMicrotasks()
+      expect(global.fetch).toHaveBeenCalledWith('https://example.com/data.geojson')
+      expect(source.getFeatures()).toHaveLength(1)
+    })
+
+    it('promotes idStrategy onto fetched features', async () => {
+      global.fetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ type: 'FeatureCollection', features: [point('native', [0, 0], { ref: 'abc' })] })
+      })
+      const registryDataset = { id: 'ds', idStrategy: 'ref', source: { type: 'geojson', data: 'https://example.com/data.geojson' } }
+
+      const source = createDatasetSource(registryDataset)
+      await flushMicrotasks()
+
+      expect(source.getFeatures()[0].getId()).toBe('abc')
+    })
+
+    it('warns and leaves the source empty when the fetch response is not ok', async () => {
+      global.fetch.mockResolvedValue({ ok: false, status: 404, statusText: 'Not Found' })
+      const registryDataset = { id: 'ds-404', idStrategy: null, source: { type: 'geojson', data: 'https://example.com/missing.geojson' } }
+
+      const source = createDatasetSource(registryDataset)
+      await flushMicrotasks()
+
+      expect(source.getFeatures()).toHaveLength(0)
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('ds-404'))
+    })
+
+    it('warns when the fetch itself rejects', async () => {
+      global.fetch.mockRejectedValue(new Error('network down'))
+      const registryDataset = { id: 'ds-fail', idStrategy: null, source: { type: 'geojson', data: 'https://example.com/data.geojson' } }
+
+      createDatasetSource(registryDataset)
+      await flushMicrotasks()
+
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('ds-fail'))
+    })
+  })
+})
+
+describe('createDatasetLayer', () => {
+  // Hex, not a named colour ('blue') — ol/style/flat resolves named CSS colours via a real
+  // canvas 2D context, which jsdom returns null for without the `canvas` npm package. Hex
+  // colours take OL's fast lane and skip that path entirely (see ol/color.js#parseRgba).
+  // Named colours work fine in a real browser; this is a test-environment gap only.
+  const registryDataset = { flatStyle: { 'fill-color': '#0000ff' }, opacity: 0.5, visibility: 'visible', minZoom: 1, maxZoom: 10, hasPattern: false }
+
+  it('builds a Canvas VectorLayer', () => {
+    const layer = createDatasetLayer(registryDataset, new VectorSource())
+    expect(layer).toBeInstanceOf(VectorLayer)
+    expect(layer.getOpacity()).toBe(0.5)
+    expect(layer.getVisible()).toBe(true)
+  })
+
+  it('sets visible to false when the dataset visibility is "none"', () => {
+    const layer = createDatasetLayer({ ...registryDataset, visibility: 'none' }, new VectorSource())
+    expect(layer.getVisible()).toBe(false)
+  })
+
+  it('tags the layer with layerType and layerId so the OL provider\'s queryFeatures recognises it', () => {
+    const layer = createDatasetLayer({ ...registryDataset, id: 'my-dataset' }, new VectorSource())
+    expect(layer.get('layerType')).toBe('vector')
+    expect(layer.get('layerId')).toBe('my-dataset')
+  })
+
+  describe('minZoom/maxZoom semantics', () => {
+    // OL's own visibility check (ol/layer/Layer.js) is `zoom > minZoom && zoom <= maxZoom` —
+    // exclusive-min, inclusive-max. MapLibre/the Mapbox style spec is the opposite:
+    // inclusive-min, exclusive-max (`zoom >= minzoom && zoom < maxzoom`). Without compensating,
+    // a dataset's minZoom:6 (matching this app's own shared default) would incorrectly hide at
+    // exactly zoom 6 in OL, when MapLibre would still show it there.
+    const isVisibleAtZoom = (layer, zoom) => zoom > layer.getMinZoom() && zoom <= layer.getMaxZoom()
+
+    it('shows the layer AT its minZoom, matching MapLibre\'s inclusive-min (not OL\'s native exclusive-min)', () => {
+      const layer = createDatasetLayer({ ...registryDataset, minZoom: 6, maxZoom: 20 }, new VectorSource())
+      expect(isVisibleAtZoom(layer, 6)).toBe(true)
+    })
+
+    it('hides the layer AT its maxZoom, matching MapLibre\'s exclusive-max (not OL\'s native inclusive-max)', () => {
+      const layer = createDatasetLayer({ ...registryDataset, minZoom: 6, maxZoom: 20 }, new VectorSource())
+      expect(isVisibleAtZoom(layer, 20)).toBe(false)
+    })
+
+    it('still shows the layer comfortably within its zoom range', () => {
+      const layer = createDatasetLayer({ ...registryDataset, minZoom: 6, maxZoom: 20 }, new VectorSource())
+      expect(isVisibleAtZoom(layer, 12)).toBe(true)
+    })
+
+    it('still hides the layer comfortably outside its zoom range', () => {
+      const layer = createDatasetLayer({ ...registryDataset, minZoom: 6, maxZoom: 20 }, new VectorSource())
+      expect(isVisibleAtZoom(layer, 5)).toBe(false)
+      expect(isVisibleAtZoom(layer, 21)).toBe(false)
+    })
+
+    it('leaves unrestricted (undefined) zoom bounds alone', () => {
+      const layer = createDatasetLayer({ ...registryDataset, minZoom: undefined, maxZoom: undefined }, new VectorSource())
+      expect(layer.getMinZoom()).toBe(-Infinity)
+      expect(layer.getMaxZoom()).toBe(Infinity)
+    })
+  })
+
+  describe('z-ordering', () => {
+    it('gives a fill/stroke dataset the default zIndex', () => {
+      const layer = createDatasetLayer(registryDataset, new VectorSource())
+      expect(layer.getZIndex()).toBe(0)
+    })
+
+    it('gives a symbol dataset a higher zIndex, so it always renders above fill/stroke layers', () => {
+      const layer = createDatasetLayer({ ...registryDataset, hasSymbol: true }, new VectorSource())
+      expect(layer.getZIndex()).toBeGreaterThan(0)
+    })
+  })
+
+  describe('tile-backed dataset', () => {
+    const tileRegistryDataset = { flatStyle: { 'stroke-color': '#0000ff' }, opacity: 1, visibility: 'visible', hasPattern: false, id: 'existing-fields' }
+    // A real VectorTileSource, built the same way createDatasetSource does — a bare
+    // `new VectorTileSource()` throws without a resolved projection.
+    const tileSource = () => createDatasetSource({ id: 'existing-fields', idStrategy: null, source: { type: 'vector', tiles: ['https://example.com/{z}/{x}/{y}'] } })
+
+    it('builds a Canvas VectorTileLayer for a VectorTileSource', () => {
+      const layer = createDatasetLayer(tileRegistryDataset, tileSource())
+      expect(layer).toBeInstanceOf(VectorTileLayer)
+    })
+
+    it('renders true vector geometry every frame, not the hybrid raster-tile default', () => {
+      const layer = createDatasetLayer(tileRegistryDataset, tileSource())
+      expect(layer.getRenderMode()).toBe('vector')
+    })
+
+    it('tags a tile-backed layer as layerType "vectorTile", not "vector"', () => {
+      const layer = createDatasetLayer(tileRegistryDataset, tileSource())
+      expect(layer.get('layerType')).toBe('vectorTile')
+      expect(layer.get('layerId')).toBe('existing-fields')
+    })
+  })
+})