@defra/interactive-map 0.0.40-alpha → 0.0.42-alpha

package/docs/examples/add-polygons.mdx

@@ -15,6 +15,7 @@ Use the datasets plugin to overlay GeoJSON polygon data on your map. This exampl
       import InteractiveMap from '@defra/interactive-map'
       import maplibreProvider from '@defra/interactive-map/providers/maplibre'
       import createDatasetsPlugin from '@defra/interactive-map/plugins/datasets'
+      import createMapKeyPlugin from '@defra/interactive-map/plugins/map-key'
 
       // GeoJSON can also be loaded from a URL; use the tiles property for vector tile sources
       const geojson = {
@@ -100,6 +101,8 @@ Use the datasets plugin to overlay GeoJSON polygon data on your map. This exampl
         }]
       })
 
+      const mapKeyPlugin = createMapKeyPlugin()
+
       new InteractiveMap('my-map', {
         behaviour: 'inline',
         mapProvider: maplibreProvider(),
@@ -110,7 +113,7 @@ Use the datasets plugin to overlay GeoJSON polygon data on your map. This exampl
         center: [-2.464, 54.558],
         zoom: 14,
         containerHeight: '516px',
-        plugins: [datasetsPlugin]
+        plugins: [datasetsPlugin, mapKeyPlugin]
       })
     `
   },
@@ -121,6 +124,7 @@ Use the datasets plugin to overlay GeoJSON polygon data on your map. This exampl
       <script src="/your-assets-path/interactive-map/index.js"></script>
       <script src="/your-assets-path/maplibre-provider/index.js"></script>
       <script src="/your-assets-path/datasets-plugin/index.js"></script>
+      <script src="/your-assets-path/map-key-plugin/index.js"></script>
 
       <script>
       // GeoJSON can also be loaded from a URL; use the tiles property for vector tile sources
@@ -207,6 +211,8 @@ Use the datasets plugin to overlay GeoJSON polygon data on your map. This exampl
         }]
       })
 
+      const mapKeyPlugin = defra.mapKeyPlugin()
+
       new defra.InteractiveMap('my-map', {
         behaviour: 'inline',
         mapProvider: defra.maplibreProvider(),
@@ -217,7 +223,7 @@ Use the datasets plugin to overlay GeoJSON polygon data on your map. This exampl
         center: [-2.464, 54.558],
         zoom: 14,
         containerHeight: '516px',
-        plugins: [datasetsPlugin]
+        plugins: [datasetsPlugin, mapKeyPlugin]
       })
       </script>
     `

package/docs/examples/add-symbols.mdx

@@ -15,6 +15,7 @@ Use the datasets plugin to overlay GeoJSON data on your map. Each dataset can co
       import InteractiveMap from '@defra/interactive-map'
       import maplibreProvider from '@defra/interactive-map/providers/maplibre'
       import createDatasetsPlugin from '@defra/interactive-map/plugins/datasets'
+      import createMapKeyPlugin from '@defra/interactive-map/plugins/map-key'
 
       const symbolGraphic = 'M3 15H1V1h2v2h2V1h2v5h2V4h2v2h2V4h2v11H6V9H3v6z'
 
@@ -76,6 +77,8 @@ Use the datasets plugin to overlay GeoJSON data on your map. Each dataset can co
         }]
       })
 
+      const mapKeyPlugin = createMapKeyPlugin()
+
       new InteractiveMap('my-map', {
         behaviour: 'inline',
         mapProvider: maplibreProvider(),
@@ -86,7 +89,7 @@ Use the datasets plugin to overlay GeoJSON data on your map. Each dataset can co
         center: [-2.4608, 54.5574],
         zoom: 14,
         containerHeight: '516px',
-        plugins: [datasetsPlugin]
+        plugins: [datasetsPlugin, mapKeyPlugin]
       })
     `
   },
@@ -97,6 +100,7 @@ Use the datasets plugin to overlay GeoJSON data on your map. Each dataset can co
       <script src="/your-assets-path/interactive-map/index.js"></script>
       <script src="/your-assets-path/maplibre-provider/index.js"></script>
       <script src="/your-assets-path/datasets-plugin/index.js"></script>
+      <script src="/your-assets-path/map-key-plugin/index.js"></script>
 
       <script>
       const symbolGraphic = 'M3 15H1V1h2v2h2V1h2v5h2V4h2v2h2V4h2v11H6V9H3v6z'
@@ -159,6 +163,8 @@ Use the datasets plugin to overlay GeoJSON data on your map. Each dataset can co
         }]
       })
 
+      const mapKeyPlugin = defra.mapKeyPlugin()
+
       new defra.InteractiveMap('my-map', {
         behaviour: 'inline',
         mapProvider: defra.maplibreProvider(),
@@ -169,7 +175,7 @@ Use the datasets plugin to overlay GeoJSON data on your map. Each dataset can co
         center: [-2.4608, 54.5574],
         zoom: 14,
         containerHeight: '516px',
-        plugins: [datasetsPlugin]
+        plugins: [datasetsPlugin, mapKeyPlugin]
       })
       </script>
     `

package/docs/examples/draw-tools.mdx

@@ -19,7 +19,7 @@ This example configures snapping (`snapLayers`) against the base map style's woo
       import InteractiveMap from '@defra/interactive-map'
       import maplibreProvider from '@defra/interactive-map/providers/maplibre'
       import createInteractPlugin from '@defra/interactive-map/plugins/interact'
-      import createDrawPlugin from '@defra/interactive-map/plugins/draw-ml'
+      import createDrawPlugin from '@defra/interactive-map/plugins/draw'
 
       const DRAW_LAYERS = ['fill-inactive.cold', 'stroke-inactive.cold']
 
@@ -149,7 +149,7 @@ This example configures snapping (`snapLayers`) against the base map style's woo
       <script src="/your-assets-path/interactive-map/index.js"></script>
       <script src="/your-assets-path/maplibre-provider/index.js"></script>
       <script src="/your-assets-path/interact-plugin/index.js"></script>
-      <script src="/your-assets-path/draw-ml-plugin/index.js"></script>
+      <script src="/your-assets-path/draw-plugin/index.js"></script>
 
       <script>
       const DRAW_LAYERS = ['fill-inactive.cold', 'stroke-inactive.cold']
@@ -165,7 +165,7 @@ This example configures snapping (`snapLayers`) against the base map style's woo
       })
 
       // Snap new vertices to the woodland layer when drawing near one
-      const drawPlugin = defra.drawMLPlugin({
+      const drawPlugin = defra.drawPlugin({
         snapLayers: ['OS/Woodland:3/Local/1']
       })
 

package/docs/plugins/datasets.md

@@ -1,6 +1,9 @@
 # Datasets Plugin
 
-The datasets plugin renders GeoJSON and vector tile datasets on the map, with support for polygon, line, and symbol (point) layer types, sublayer style rules, layer visibility toggling, a key panel, and runtime style and data updates.
+The datasets plugin renders GeoJSON and vector tile datasets on the map, with support for polygon, line, and symbol (point) layer types, sublayer style rules, layer visibility toggling, and runtime style and data updates.
+
+> [!IMPORTANT]
+> **Upgrading?** This plugin no longer renders key of symbols itself — that button and panel have been removed. Add the [Map Key](./map-key.md) plugin to restore it. Your `showInKey` config is unaffected and needs no changes.
 
 ## ESM usage
 
@@ -282,6 +285,9 @@ Initial visibility of the dataset.
 
 When `true`, the dataset appears in the Key panel with its style symbol and label. Sublayers inherit this value — set `showInKey: false` on an individual sublayer to opt it out.
 
+> [!NOTE]
+> Rendering the Key panel requires the [Map Key](./map-key.md) plugin to be added alongside this one — `showInKey` has no visible effect on its own.
+
 ---
 
 ### `showInMenu`
@@ -303,9 +309,7 @@ Groups this dataset with others sharing the same `groupLabel` in the LayersMenu
 
 ### `keySymbolShape`
 
-**Type:** `'polygon' | 'line'`
-
-Overrides the shape used to render the key symbol for this dataset. Defaults to a polygon shape.
+Set within [`style`](#style) — not a top-level dataset property. See [Map Key: `keySymbolShape`](./map-key.md#keysymbolshape).
 
 ---
 
@@ -340,21 +344,25 @@ Visual style for the dataset. All style properties must be nested within this ob
 
 Setting `symbol` or `symbolSvgContent` renders the dataset as a point layer instead of a polygon/line layer.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `symbol` | `string` | Registered symbol ID e.g. `'pin'`, `'circle'`, `'square'` |
-| `symbolSvgContent` | `string` | Inline SVG content for a fully custom symbol (no `<svg>` wrapper). Takes precedence over `symbol` |
-| `symbolViewBox` | `string` | SVG viewBox for the symbol e.g. `'0 0 38 38'`. Defaults to the registered symbol's viewBox |
-| `symbolAnchor` | `[number, number]` | Anchor point as a normalised `[x, y]` pair. Defaults to the registered symbol's anchor |
-| `symbolBackgroundColor` | `string \| Record<string, string>` | Background fill colour of the symbol |
-| `symbolForegroundColor` | `string \| Record<string, string>` | Foreground fill colour of the symbol (e.g. the inner dot) |
-| `symbolHaloWidth` | `string` | Stroke width of the halo in SVG units |
-| `symbolGraphic` | `string` | SVG `d` attribute for the foreground graphic path. Use named values (`'dot'`, `'cross'`, `'diamond'`, `'triangle'`, `'square'`) or supply your own path data |
+Each is documented in full in [Symbol Config](../api/symbol-config.md), under a `symbol` prefix here to distinguish them from the polygon/line properties in the same style object:
 
-Symbol colour properties use the `symbol` prefix to distinguish them from polygon/line properties in the same style object. They follow the same resolution order and support style-keyed colour objects in the same way as markers — see [Symbol Config](../api/symbol-config.md) for details.
+| Property | Symbol Config property |
+|----------|-------------------------|
+| `symbol` | [`symbol`](../api/symbol-config.md#symbol) |
+| `symbolSvgContent` | [`symbolSvgContent`](../api/symbol-config.md#symbolsvgcontent) |
+| `symbolViewBox` | [`viewBox`](../api/symbol-config.md#viewbox) |
+| `symbolAnchor` | [`anchor`](../api/symbol-config.md#anchor) |
+| `symbolBackgroundColor` | [`backgroundColor`](../api/symbol-config.md#backgroundcolor) |
+| `symbolForegroundColor` | [`foregroundColor`](../api/symbol-config.md#foregroundcolor) |
+| `symbolHaloWidth` | Stroke width of the halo in SVG units. Not currently documented in Symbol Config |
+| `symbolGraphic` | [`graphic`](../api/symbol-config.md#graphic) |
+
+They follow the same resolution order and support style-keyed colour objects in the same way as markers.
 
 `haloColor` and `selectedColor` are not settable here — they are basemap-level properties set on [`MapStyleConfig`](../api/map-style-config.md).
 
+`symbolDescription` and `keySymbolShape` only affect how an entry looks in the Key panel — see [Map Key: Key display properties](./map-key.md#key-display-properties) for details.
+
 ```js
 // Polygon/line dataset
 style: {

package/docs/plugins/draw.md

@@ -1,6 +1,6 @@
 # Draw Plugin
 
-The draw plugin lets users draw and edit polygon and line features on the map — placing vertices by click, tap, or keyboard, snapping to existing map layers, and validating geometry as it's built. Polygons can also be split and merged. It works identically with both the MapLibre and OpenLayers map providers, determining the correct adapter to use from the `mapProvider` passed to `InteractiveMap` — there's nothing to configure.
+The draw plugin lets users draw and edit point, polygon and line features on the map — placing vertices by click, tap, or keyboard, snapping to existing map layers, and validating geometry as it's built. Polygons can also be split and merged. It works identically with both the MapLibre and OpenLayers map providers, determining the correct adapter to use from the `mapProvider` passed to `InteractiveMap` — there's nothing to configure.
 
 ## ESM usage
 
@@ -54,7 +54,7 @@ Options are passed to the factory function when creating the plugin.
 
 **Type:** `string[]`
 
-Vector tile source-layer names to snap new and edited vertices against. Can be overridden per call — see `newPolygon`, `newLine`, `editFeature`, and `split` below.
+Vector tile source-layer names to snap new and edited vertices against. Can be overridden per call — see `newPolygon`, `newLine`, `newPoint`, `editFeature`, and `split` below.
 
 The layer names available depend entirely on your basemap style — there's no universal default, so check your style's vector tile source(s) for the source-layer names to use. The example below (`'OS/TopographicArea_1/Agricultural Land'`) is specific to an Ordnance Survey basemap style.
 
@@ -72,7 +72,7 @@ createDrawPlugin({
 
 **Type:** `Function`
 
-Plugin-level validation callback, called throughout the draw/edit lifecycle so you can enforce your own rules (e.g. "shapes must stay inside a boundary") alongside the built-in ones. Can be overridden per call — see [Validation](#validation) below for the full contract, and `newPolygon`, `newLine`, `editFeature` for the per-call override.
+Plugin-level validation callback, called throughout the draw/edit lifecycle so you can enforce your own rules (e.g. "shapes must stay inside a boundary") alongside the built-in ones. Can be overridden per call — see [Validation](#validation) below for the full contract, and `newPolygon`, `newLine`, `newPoint`, `editFeature` for the per-call override.
 
 ---
 
@@ -141,7 +141,7 @@ Rule failures gate the Done button (the shape can pass through interim invalid s
 
 ### `onGeometryChange` callback
 
-Set at the plugin level (`createDrawPlugin({ onGeometryChange })`) or per call (`newPolygon`/`newLine`/`editFeature`'s `options.onGeometryChange`, which takes precedence when given). Not used by `split` (which validates that the line actually bisects the shape) or `merge`/`addFeature` (no validation).
+Set at the plugin level (`createDrawPlugin({ onGeometryChange })`) or per call (`newPolygon`/`newLine`/`newPoint`/`editFeature`'s `options.onGeometryChange`, which takes precedence when given). Not used by `split` (which validates that the line actually bisects the shape) or `merge`/`addFeature`/`setStyle` (no validation). For a `Point`, only the `'place'` phase applies — placing or dragging a point can be vetoed, but there's no minimum-vertices/self-intersection/area check.
 
 **Signature:** `onGeometryChange(event) => boolean | { valid: boolean, reason?: string } | undefined`
 
@@ -157,7 +157,7 @@ Set at the plugin level (`createDrawPlugin({ onGeometryChange })`) or per call (
 |----------|------|-------------|
 | `feature` | `GeoJSON.Feature` | The shape at this point — the in-progress feature during `'preview'`, the committed/candidate feature at every other phase |
 | `phase` | `string` | See table below |
-| `mode` | `'draw_polygon' \| 'draw_line' \| 'edit_vertex'` | The active draw mode |
+| `mode` | `'draw_polygon' \| 'draw_line' \| 'draw_point' \| 'edit_vertex' \| 'edit_point'` | The active draw mode |
 | `vertexIndex` | `number` | Index of the vertex being placed/added/moved/inserted/deleted. Present on `'place'` and every `'commit-*'` phase |
 | `numVertices` | `number` | Count of already-committed vertices, excluding any in-progress cursor point. Present on every `'preview'` call |
 
@@ -185,7 +185,7 @@ createDrawPlugin({
 
 ## Methods
 
-Methods are called on the plugin instance. `newPolygon`, `newLine`, `editFeature`, `addFeature`, `deleteFeature`, `split`, and `merge` all need `mapProvider.draw` to be ready — call them after [`draw:ready`](#drawready).
+Methods are called on the plugin instance. `newPolygon`, `newLine`, `newPoint`, `editFeature`, `addFeature`, `setStyle`, `deleteFeature`, `split`, and `merge` all need `mapProvider.draw` to be ready — call them after [`draw:ready`](#drawready).
 
 ---
 
@@ -225,9 +225,39 @@ drawPlugin.newLine(crypto.randomUUID(), {
 
 ---
 
+### `newPoint(featureId, options?)`
+
+Start drawing a new point. Unlike `newPolygon`/`newLine`, it commits as soon as a point is placed — there's no Done step.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `featureId` | `string` | **Required.** ID to assign the finished feature |
+| `options.snapLayers` | `string[]` | Overrides the plugin-level `snapLayers` for this session |
+| `options.onGeometryChange` | `Function` | Overrides the plugin-level `onGeometryChange` for this session — see [Validation](#validation) |
+| `options.properties` | `Object` | Custom GeoJSON properties to set on the finished feature |
+| `options.symbol` | `string` | Built-in symbol id — `'pin'`, `'circle'`, or `'square'` |
+| `options.symbolSvgContent` | `string` | Custom SVG markup, used instead of `symbol` |
+| `options.symbolBackgroundColor` | `string \| Record<string, string>` | Symbol background colour |
+| `options.symbolForegroundColor` | `string \| Record<string, string>` | Symbol foreground colour |
+| `options.symbolGraphic` | `string` | Overrides the symbol's inner graphic (built-in name or SVG path data) |
+| `options.symbolHaloWidth` | `number` | Symbol halo width |
+| `options.symbolViewBox` | `string` | SVG `viewBox`, for use with `symbolSvgContent` |
+| `options.symbolAnchor` | `[number, number]` | Normalised `[x, y]` anchor point |
+
+These mirror [MarkerOptions](../api/marker-config.md#markeroptions)' `symbol`-family properties (prefixed with `symbol` here to sit alongside other feature properties) — see [Symbol Config](../api/symbol-config.md) for the full resolution order and SVG token structure. Points with no symbol config render with the plugin's default marker.
+
+```js
+drawPlugin.newPoint(crypto.randomUUID(), {
+  symbol: 'pin',
+  symbolBackgroundColor: { outdoor: '#d4351c', dark: '#ff6b6b' }
+})
+```
+
+---
+
 ### `editFeature(featureId, options?)`
 
-Open an existing feature in vertex-edit mode. Returns `false` (without doing anything) if the feature doesn't exist or the plugin isn't ready yet — check the return value before assuming the edit session started.
+Open an existing feature in edit mode — vertex-edit for a `Polygon`/`LineString`, single-coordinate drag for a `Point`. Returns `false` (without doing anything) if the feature doesn't exist or the plugin isn't ready yet — check the return value before assuming the edit session started.
 
 | Argument | Type | Description |
 |----------|------|-------------|
@@ -246,16 +276,19 @@ if (!editSuccess) {
 
 ### `addFeature(feature)`
 
-Add a feature directly to the map without a draw session — e.g. loading in existing shapes on `draw:ready`.
+Add a `Point`, `LineString`, or `Polygon` feature directly to the map without a draw session — e.g. loading in existing shapes on `draw:ready`.
 
 | Argument | Type | Description |
 |----------|------|-------------|
 | `feature.id` | `string` | **Required.** Feature ID |
-| `feature.geometry` | `GeoJSON.Geometry` | **Required.** `Polygon` or `LineString` geometry |
-| `feature.stroke` | `string \| Record<string, string>` | Stroke colour |
-| `feature.fill` | `string \| Record<string, string>` | Fill colour |
-| `feature.strokeWidth` | `number` | Stroke width in pixels |
-| `feature.properties` | `Object` | Custom GeoJSON properties |
+| `feature.type` | `string` | Defaults to `'Feature'` if omitted |
+| `feature.geometry` | `GeoJSON.Geometry` | **Required.** `Point`, `LineString`, or `Polygon` geometry |
+| `feature.stroke` | `string \| Record<string, string>` | Stroke colour (`LineString`/`Polygon`) |
+| `feature.fill` | `string \| Record<string, string>` | Fill colour (`Polygon`) |
+| `feature.strokeWidth` | `number` | Stroke width in pixels (`LineString`/`Polygon`) |
+| `feature.properties` | `Object` | Custom GeoJSON properties — a `Point`'s `symbol`-family properties go here (see `newPoint` above) |
+
+A feature with a missing/unsupported `geometry.type` or no `geometry.coordinates` is logged as a warning and ignored.
 
 ```js
 interactiveMap.on('draw:ready', () => {
@@ -267,11 +300,33 @@ interactiveMap.on('draw:ready', () => {
     fill: 'rgba(0,112,60,0.2)',
     strokeWidth: 2
   })
+
+  drawPlugin.addFeature({
+    id: 'monument1',
+    type: 'Feature',
+    geometry: { type: 'Point', coordinates: [-2.878, 54.709] },
+    properties: { symbol: 'square', symbolBackgroundColor: '#28a197' }
+  })
 })
 ```
 
 ---
 
+### `setStyle(featureId, styleChanges)`
+
+Update an existing feature's style — stroke/fill/strokeWidth or, for a `Point`, its `symbol`-family properties (see `newPoint` above). Only the keys you pass are changed; anything else the feature already has is left alone. Returns `false` if the feature doesn't exist.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `featureId` | `string` | **Required.** ID of the feature to update |
+| `styleChanges` | `Object` | **Required.** Any mix of `stroke`, `fill`, `strokeWidth`, or `symbol`-family properties |
+
+```js
+drawPlugin.setStyle('monument1', { symbolBackgroundColor: { outdoor: '#1d70b8', dark: '#4c9ed9' } })
+```
+
+---
+
 ### `deleteFeature(featureIds)`
 
 Remove one or more features from the map.
@@ -371,9 +426,9 @@ Emitted once the draw plugin has initialised. Safe to call API methods from here
 
 ### `draw:started`
 
-Emitted when `newPolygon` or `newLine` starts a new draw session.
+Emitted when `newPolygon`, `newLine`, or `newPoint` starts a new draw session.
 
-**Payload:** `{ mode: 'draw_polygon' | 'draw_line' }`
+**Payload:** `{ mode: 'draw_polygon' | 'draw_line' | 'draw_point' }`
 
 ---
 
@@ -381,7 +436,7 @@ Emitted when `newPolygon` or `newLine` starts a new draw session.
 
 Emitted when `editFeature` opens an existing feature for editing.
 
-**Payload:** `{ mode: 'edit_polygon' | 'edit_line' }`
+**Payload:** `{ mode: 'edit_polygon' | 'edit_line' | 'edit_point' }`
 
 ---
 
@@ -457,6 +512,14 @@ Emitted after `deleteFeature` removes a feature.
 
 ---
 
+### `draw:stylechange`
+
+Emitted after `setStyle` updates a feature's style.
+
+**Payload:** `{ featureId: string, properties: Object }` — the flattened style/symbol properties that were applied
+
+---
+
 ### `draw:split`
 
 Emitted when `split` computes a successful split.

package/docs/plugins/map-key.md

@@ -0,0 +1,147 @@
+# Map Key Plugin
+
+Renders a key of symbols present on the map, in a key panel.
+
+Today, the [Datasets](./datasets.md) plugin is wired up to it via a dedicated hook — datasets and sublayers configured with `showInKey: true` feed their styled symbols into the key panel automatically. Other plugins may hook into the key panel in future, but that isn't built yet; Datasets is currently the only integration.
+
+The plugin holds no dataset-specific config itself — when paired with the Datasets plugin, it reads dataset styling from that plugin's registry at runtime via that hook. There's nothing to configure to make that connection; both plugins just need to be present in `plugins`.
+
+> [!NOTE]
+> Buttons render in the shared `top-left` slot in the order their plugins appear in the `plugins` array — list `datasetsPlugin` before `mapKeyPlugin` to get Layers before Key.
+
+## ESM usage
+
+```js
+import createDatasetsPlugin from '@defra/interactive-map/plugins/datasets'
+import createMapKeyPlugin from '@defra/interactive-map/plugins/map-key'
+
+const datasetsPlugin = createDatasetsPlugin({
+  datasets: [
+    {
+      id: 'my-parcels',
+      label: 'My parcels',
+      geojson: 'https://example.com/api/parcels',
+      showInKey: true,
+      showInMenu: true,
+      style: {
+        stroke: '#d4351c',
+        strokeWidth: 2,
+        fill: 'transparent'
+      }
+    }
+  ]
+})
+
+const mapKeyPlugin = createMapKeyPlugin()
+
+const interactiveMap = new InteractiveMap({
+  plugins: [datasetsPlugin, mapKeyPlugin]
+})
+```
+
+## UMD usage
+
+Copy the entire `plugins/map-key/dist/umd/` directory to `/your-assets-path/plugins/map-key/umd/`. The plugin uses dynamic imports, so all files in the directory must be served from the same location. Then add the script tag alongside the Datasets plugin's:
+
+```html
+<script defer src="/your-assets-path/plugins/datasets/umd/index.js"></script>
+<script defer src="/your-assets-path/plugins/map-key/umd/index.js"></script>
+```
+
+```js
+const datasetsPlugin = defra.datasetsPlugin({
+  datasets: [
+    {
+      id: 'my-parcels',
+      label: 'My parcels',
+      geojson: 'https://example.com/api/parcels',
+      showInKey: true,
+      showInMenu: true,
+      style: {
+        stroke: '#d4351c',
+        strokeWidth: 2,
+        fill: 'transparent'
+      }
+    }
+  ]
+})
+
+const mapKeyPlugin = defra.mapKeyPlugin()
+
+const interactiveMap = new defra.InteractiveMap('map', {
+  mapProvider: defra.maplibreProvider(),
+  plugins: [datasetsPlugin, mapKeyPlugin]
+})
+```
+
+> [!NOTE]
+> **GOV.UK Prototype Kit** — skip the copy step. All files are served automatically. Use this path instead:
+> ```html
+> <script defer src="/plugin-assets/%40defra%2Finteractive-map/plugins/map-key/dist/umd/index.js"></script>
+> ```
+
+## Options
+
+Options are passed to the factory function when creating the plugin.
+
+---
+
+### `noKeyItemText`
+
+**Type:** `string`
+**Default:** `'No features displayed'`
+
+Text shown in the key panel when it has no visible entries to display — for example, no datasets or sublayers configured with `showInKey: true` currently have visible features on the map.
+
+```js
+createMapKeyPlugin({ noKeyItemText: 'No layers to show' })
+```
+
+---
+
+### `includeModes`
+
+**Type:** `string[]`
+
+When set, the plugin only initialises when the app is in one of the specified modes.
+
+---
+
+### `excludeModes`
+
+**Type:** `string[]`
+
+When set, the plugin does not initialise when the app is in one of the specified modes.
+
+---
+
+## Key display properties
+
+These properties control how an entry looks in the key panel — they have no effect on how a feature renders on the map itself. Today the only way to set them is via a dataset's [`style`](./datasets.md#style) object, since Datasets is the only plugin feeding this key panel.
+
+---
+
+### `keySymbolShape`
+
+**Type:** `'polygon' | 'line'`
+**Default:** `'polygon'`
+
+Overrides the shape used to render a polygon/line entry's symbol in the key.
+
+---
+
+### `symbolDescription`
+
+**Type:** `string | Record<string, string>`
+
+Accessible description of the symbol shown alongside its key entry.
+
+---
+
+## Methods
+
+This plugin does not expose any public methods.
+
+## Events
+
+This plugin does not emit any custom events.

package/docs/plugins/search.md

@@ -136,7 +136,7 @@ searchPlugin({
 
 Controls whether the search input is always visible or hidden behind an open button.
 
-- **Mobile** — by default the search is hidden and requires a button tap to open. When `expanded: true`, it moves to the banner slot and is shown inline at the top of the map at all times.
+- **Mobile** — the search form always lives in the `header` slot, above the top row. By default it's collapsed behind a button tap; setting `expanded: true` shows it inline at all times and removes the open button.
 - **Tablet and desktop** — the search always sits in the `top-left` slot regardless of this setting, but setting `expanded: true` removes the open button so the input is immediately visible without interaction.
 
 ---

package/docs/plugins.md

@@ -30,7 +30,11 @@ The following plugins are in early development. APIs and features may change.
 
 ### [Datasets](./plugins/datasets.md)
 
-Add datasets to your map, configure the display, layer toggling and render a key of symbology.
+Render GeoJSON and vector tile datasets on the map, with a menu for toggling layer visibility. Pair with the [Map Key](./plugins/map-key.md) plugin to render a key of symbols.
+
+### [Map Key](./plugins/map-key.md)
+
+Renders a key of symbols in a panel. Currently sourced from the Datasets plugin.
 
 ### [Draw](./plugins/draw.md)
 

package/govuk-prototype-kit.config.json

@@ -66,6 +66,8 @@
     "/plugins/draw/dist",
     "/providers/beta/open-names/dist",
     "/plugins/datasets/dist",
+    "/plugins/map-key/dist",
+    "/plugins/menu/dist",
     "/plugins/beta/map-styles/dist",
     "/plugins/beta/scale-bar/dist",
     "/plugins/beta/use-location/dist",

package/jest.setup.js

@@ -1,5 +1,10 @@
 import '@testing-library/jest-dom'
 
+// structuredClone is not exposed by jsdom; polyfill it using JSON round-trip
+if (typeof structuredClone === 'undefined') {
+  global.structuredClone = (obj) => JSON.parse(JSON.stringify(obj))
+}
+
 // Global mock for window.matchMedia
 if (!window.matchMedia) {
   Object.defineProperty(window, 'matchMedia', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/interactive-map",
-  "version": "0.0.40-alpha",
+  "version": "0.0.42-alpha",
   "description": "An accessible map component",
   "repository": {
     "type": "git",
@@ -47,6 +47,12 @@
     "./plugins/datasets": {
       "import": "./plugins/datasets/dist/esm/index.js"
     },
+    "./plugins/menu": {
+      "import": "./plugins/menu/dist/esm/index.js"
+    },
+    "./plugins/map-key": {
+      "import": "./plugins/map-key/dist/esm/index.js"
+    },
     "./plugins/datasets/adapters/maplibre": {
       "import": "./plugins/datasets/dist/adapters/maplibre/esm/index.js"
     },
@@ -69,6 +75,8 @@
     "./plugins/draw-ml/css": "./plugins/beta/draw-ml/dist/css/index.css",
     "./plugins/scale-bar/css": "./plugins/beta/scale-bar/dist/css/index.css",
     "./plugins/datasets/css": "./plugins/datasets/dist/css/index.css",
+    "./plugins/menu/css": "./plugins/menu/dist/css/index.css",
+    "./plugins/map-key/css": "./plugins/map-key/dist/css/index.css",
     "./plugins/frame/css": "./plugins/beta/frame/dist/css/index.css",
     "./plugins/map-styles/css": "./plugins/beta/map-styles/dist/css/index.css",
     "./plugins/search/css": "./plugins/search/dist/css/index.css",