@defra/interactive-map 0.0.18-alpha → 0.0.20-alpha

package/docs/examples/add-marker-with-panel.mdx

@@ -0,0 +1,123 @@
+import DemoMapMarkerPanel from '../../demo/DemoMapMarkerPanel.js'
+import CodeTabs from '../../demo/js/codeTabs.js'
+
+# Add a marker with a panel
+
+Add markers to the map and allow users to select them. Selecting a marker fires the `interact:selectionchange` event, which can be used to show a panel with relevant information.
+
+<DemoMapMarkerPanel />
+
+<CodeTabs tabs={[
+  {
+    label: 'ESM',
+    language: 'js',
+    code: `
+      import InteractiveMap from '@defra/interactive-map'
+      import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+      import createInteractPlugin from '@defra/interactive-map/plugins/interact'
+
+      const interactPlugin = createInteractPlugin({
+        deselectOnClickOutside: true
+      })
+
+      const map = new InteractiveMap('my-map', {
+        behaviour: 'inline',
+        mapProvider: maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-2.96, 54.43],
+        zoom: 15,
+        containerHeight: '500px',
+        plugins: [interactPlugin]
+      })
+
+      map.on('map:ready', () => {
+        map.addMarker('my-marker', [-2.96, 54.43])
+        interactPlugin.enable()
+        interactPlugin.selectMarker('my-marker')
+
+        map.addPanel('marker-info', {
+          focus: false,
+          label: 'Marker',
+          html: '<p class="govuk-body">Information about the selected marker</p>',
+          mobile: { slot: 'drawer', dismissible: true },
+          tablet: { slot: 'left-top', dismissible: true, width: '280px' },
+          desktop: { slot: 'left-top', dismissible: true, width: '280px' }
+        })
+      })
+
+      map.on('interact:selectionchange', ({ selectedMarkers }) => {
+        if (selectedMarkers.length > 0) {
+          map.showPanel('marker-info')
+        } else {
+          map.hidePanel('marker-info')
+        }
+      })
+
+      map.on('app:panelclosed', ({ panelId }) => {
+        if (panelId === 'marker-info') {
+          interactPlugin.unselectMarker('my-marker')
+        }
+      })
+    `
+  },
+  {
+    label: 'UMD',
+    language: 'html',
+    code: `
+      <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>
+      const interactPlugin = defra.interactPlugin({
+        deselectOnClickOutside: true
+      })
+
+      const map = new defra.InteractiveMap('my-map', {
+        behaviour: 'inline',
+        mapProvider: defra.maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-2.96, 54.43],
+        zoom: 15,
+        containerHeight: '500px',
+        plugins: [interactPlugin]
+      })
+
+      map.on('map:ready', () => {
+        map.addMarker('my-marker', [-2.96, 54.43])
+        interactPlugin.enable()
+        interactPlugin.selectMarker('my-marker')
+
+        map.addPanel('marker-info', {
+          focus: false,
+          label: 'Marker',
+          html: '<p class="govuk-body">Information about the selected marker</p>',
+          mobile: { slot: 'drawer', dismissible: true },
+          tablet: { slot: 'left-top', dismissible: true, width: '280px' },
+          desktop: { slot: 'left-top', dismissible: true, width: '280px' }
+        })
+      })
+
+      map.on('interact:selectionchange', ({ selectedMarkers }) => {
+        if (selectedMarkers.length > 0) {
+          map.showPanel('marker-info')
+        } else {
+          map.hidePanel('marker-info')
+        }
+      })
+
+      map.on('app:panelclosed', ({ panelId }) => {
+        if (panelId === 'marker-info') {
+          interactPlugin.unselectMarker('my-marker')
+        }
+      })
+      </script>
+    `
+  }
+]} />

package/docs/examples/basic-map.mdx

@@ -0,0 +1,53 @@
+import DemoMapBasic from '../../demo/DemoMapBasic.js'
+import CodeTabs from '../../demo/js/codeTabs.js'
+
+# Basic map
+
+Embed an interactive map directly on the page, allowing users to explore and interact with the map without leaving the current context.
+
+<DemoMapBasic />
+
+<CodeTabs tabs={[
+  {
+    label: 'ESM',
+    language: 'js',
+    code: `
+      import InteractiveMap from '@defra/interactive-map'
+      import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+
+      new InteractiveMap('my-map', {
+        behaviour: 'inline',
+        mapProvider: maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-1.6, 53.1],
+        zoom: 6,
+        containerHeight: '500px'
+      })
+    `
+  },
+  {
+    label: 'UMD',
+    language: 'html',
+    code: `
+      <script src="/your-assets-path/interactive-map/index.js"></script>
+      <script src="/your-assets-path/maplibre-provider/index.js"></script>
+
+      <script>
+      new defra.InteractiveMap('my-map', {
+        behaviour: 'inline',
+        mapProvider: defra.maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-1.6, 53.1],
+        zoom: 6,
+        containerHeight: '500px'
+      })
+      </script>
+    `
+  }
+]} />

package/docs/examples/button-map.mdx

@@ -0,0 +1,53 @@
+import DemoMapButton from '../../demo/DemoMapButton.js'
+import CodeTabs from '../../demo/js/codeTabs.js'
+
+# Button-triggered map
+
+Trigger the map to show on button press, allowing users to access the map when needed without it taking up space on the page by default.
+
+<DemoMapButton />
+
+<CodeTabs tabs={[
+  {
+    label: 'ESM',
+    language: 'js',
+    code: `
+      import InteractiveMap from '@defra/interactive-map'
+      import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+
+      new InteractiveMap('my-map', {
+        behaviour: 'buttonFirst',
+        mapProvider: maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-1.6, 53.1],
+        zoom: 6,
+        hasExitButton: true
+      })
+    `
+  },
+  {
+    label: 'UMD',
+    language: 'html',
+    code: `
+      <script src="/your-assets-path/interactive-map/index.js"></script>
+      <script src="/your-assets-path/maplibre-provider/index.js"></script>
+
+      <script>
+      new defra.InteractiveMap('my-map', {
+        behaviour: 'buttonFirst',
+        mapProvider: defra.maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-1.6, 53.1],
+        zoom: 6,
+        hasExitButton: true
+      })
+      </script>
+    `
+  }
+]} />

package/docs/examples/index.mdx

@@ -0,0 +1,49 @@
+import useBaseUrl from '@docusaurus/useBaseUrl'
+import basicMapImg from '../assets/images/basic-map.jpg'
+import buttonFirstImg from '../assets/images/button-first.jpg'
+import markerPanelImg from '../assets/images/marker-panel.jpg'
+
+export function ExampleCards() {
+  const basicHref = useBaseUrl('/examples/basic-map')
+  const buttonHref = useBaseUrl('/examples/button-map')
+  const interactHref = useBaseUrl('/examples/add-marker-with-panel')
+
+  return (
+    <div className='govuk-grid-row'>
+      <div className='govuk-grid-column-one-half'>
+        <div className='app-example-card'>
+          <img src={basicMapImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-m'>
+              <a href={basicHref}>Basic map</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-half'>
+        <div className='app-example-card'>
+          <img src={buttonFirstImg} alt='' />
+          <div className='app-example-card__body' style={{ borderTop: '1px solid #f4f8fb'}}>
+            <h2 className='govuk-heading-m'>
+              <a href={buttonHref}>Button-triggered map</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-half'>
+        <div className='app-example-card'>
+          <img src={markerPanelImg} alt='' />
+          <div className='app-example-card__body' style={{ borderTop: '1px solid #f4f8fb'}}>
+            <h2 className='govuk-heading-m'>
+              <a href={interactHref}>Add a marker with a panel</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+# Examples
+
+<ExampleCards />

package/docs/getting-started.md

@@ -3,62 +3,61 @@
 ## Installation
 
 ```shell
-npm i @defra/interactive-map@x.y.z-alpha
+npm install @defra/interactive-map@x.y.z-alpha
 ```
 
-[!NOTE]  
-Install using a fixed version (e.g. npm install @defra/interactive-map@x.y.z-alpha) as this package is currently in alpha and may introduce breaking changes. Check the GitHub releases page for the latest available [version](https://github.com/DEFRA/interactive-map/tags).
+> [!NOTE]
+Install using a fixed version (e.g. `npm install @defra/interactive-map@x.y.z-alpha`) as this package is currently in alpha and may introduce breaking changes. Check the GitHub releases page for the latest available [version](https://github.com/DEFRA/interactive-map/tags).
 
-### MapLibre provider (recommended)
+## GOV.UK Prototype kit
 
-**ESM:** `maplibre-gl` is a peer dependency, install it separately:
+The quickest way to get started is via the GOV.UK Prototype Kit. Once installed, the map component is available immediately — no build step or manual asset setup required.
 
-```shell
-npm i maplibre-gl
-```
+The plugin automatically serves the required scripts and styles, and provides a ready-made map page template to build from.
 
-**UMD:** `maplibre-gl` is bundled — no separate install needed.
+See [GOV.UK Prototype Kit - Install and use plugins](https://prototype-kit.service.gov.uk/docs/install-and-use-plugins) for how to install plugins.
 
-### ESRI provider (optional)
+## Manual setup
 
-If you are using the ESRI map provider instead, install `@arcgis/core`:
+The package is distributed in two formats:
 
-```shell
-npm i @arcgis/core
-```
+- **ESM** (ECMAScript Modules) — for projects using a bundler such as Webpack or Rollup. Import directly from the package in your JavaScript.
+- **UMD** (Universal Module Definition) — for projects without a bundler. Copy the built files to your assets and load them via `<script>` tags.
 
-### Include in your project
+The map component also requires a **map provider** — a separate library that handles the underlying tile rendering engine. The provider is passed in at initialisation, which keeps the core package lean and lets you choose the engine that fits your needs.
 
-**ESM** — import in your JavaScript:
+### MapLibre provider (recommended)
 
-```js
-import InteractiveMap from '@defra/interactive-map'
-import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+**ESM:** `maplibre-gl` is a peer dependency, install it separately:
 
-import '@defra/interactive-map/css'
+```shell
+npm install maplibre-gl
 ```
 
-**UMD** — copy the `dist/umd/` folders to your assets and include via script and link tags in your `<head>`:
+**UMD:** `maplibre-gl` is bundled — no separate install needed.
+
+### ESRI provider (optional)
 
-```html
-<link rel="stylesheet" href="/assets/interactive-map.css">
-<script defer src="/assets/interactive-map/index.js"></script>
-<script defer src="/assets/maplibre-provider/index.js"></script>
-```
+The ESRI provider is available for ESM projects only. Install `@arcgis/core` separately:
 
-> Chunks are loaded dynamically — all files in each `umd/` folder must be served from the same directory as their `index.js`.
+```shell
+npm install @arcgis/core
+```
 
 ## Basic usage
 
-Add a container element in your HTML:
+**ESM** — add a container element to your HTML and initialise the map in your JavaScript:
 
 ```html
 <div id="map"></div>
 ```
 
-Initialise the map in your JavaScript. UMD users replace `InteractiveMap` and `maplibreProvider` with `defra.InteractiveMap` and `defra.maplibreProvider`:
-
 ```js
+import InteractiveMap from '@defra/interactive-map'
+import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+
+import '@defra/interactive-map/css'
+
 const interactiveMap = new InteractiveMap('map', {
   mapProvider: maplibreProvider(),
   behaviour: 'hybrid',
@@ -74,44 +73,72 @@ const interactiveMap = new InteractiveMap('map', {
 })
 ```
 
+**UMD** — copy the `dist/umd/` folders to your assets, then use this page skeleton as a starting point:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Map</title>
+    <link rel="stylesheet" href="/your-assets-path/interactive-map.css">
+    <script defer src="/your-assets-path/interactive-map/index.js"></script>
+    <script defer src="/your-assets-path/maplibre-provider/index.js"></script>
+    <script defer>
+      document.addEventListener('DOMContentLoaded', function () {
+        const interactiveMap = new defra.InteractiveMap('map', {
+          mapProvider: defra.maplibreProvider(),
+          behaviour: 'hybrid',
+          mapLabel: 'Ambleside',
+          zoom: 14,
+          center: [-2.968, 54.425],
+          containerHeight: '650px',
+          mapStyle: {
+            url: 'https://tiles.openfreemap.org/styles/liberty',
+            attribution: 'OpenFreeMap © OpenMapTiles Data from OpenStreetMap',
+            backgroundColor: '#f5f5f0'
+          }
+        })
+      })
+    </script>
+  </head>
+  <body>
+    <div id="map"></div>
+  </body>
+</html>
+```
+
+> [!NOTE]
+> Scripts are loaded dynamically — all files in each `umd/` folder must be served from the same directory as their `index.js`.
+
 ## Using plugins
 
-**ESM** — import each plugin and its CSS:
+**ESM** — add the plugin import and its CSS alongside your existing core imports, then pass it to `plugins`:
 
 ```js
-import createSearchPlugin from '@defra/interactive-map/plugins/search'
 import createInteractPlugin from '@defra/interactive-map/plugins/interact'
-
-import '@defra/interactive-map/plugins/search/css'
 import '@defra/interactive-map/plugins/interact/css'
+
+const interactiveMap = new InteractiveMap('map', {
+  // ...your existing options
+  plugins: [createInteractPlugin()]
+})
 ```
 
-**UMD** — copy each plugin's `dist/umd/` folder and CSS file to your assets:
+**UMD** — copy the plugin's `dist/umd/` folder to your assets if you haven't already, then add its script and CSS to your page skeleton:
 
 ```html
-<link rel="stylesheet" href="/assets/search-plugin.css">
-<link rel="stylesheet" href="/assets/interact-plugin.css">
-<script src="/assets/search-plugin/index.js"></script>
-<script src="/assets/interact-plugin/index.js"></script>
+<link rel="stylesheet" href="/your-assets-path/interact-plugin.css">
+<script defer src="/your-assets-path/interact-plugin/index.js"></script>
 ```
 
-Then pass plugins when initialising. UMD users replace `createSearchPlugin` and `createInteractPlugin` with `defra.searchPlugin` and `defra.interactPlugin`:
+Then pass the plugin in your initialisation:
 
 ```js
-const interactiveMap = new InteractiveMap('map', {
-  mapProvider: maplibreProvider(),
-  plugins: [
-    createSearchPlugin(),
-    createInteractPlugin()
-  ],
-  // ... other options
+const interactiveMap = new defra.InteractiveMap('map', {
+  // ...your existing options
+  plugins: [defra.interactPlugin()]
 })
 ```
 
 Each plugin distributes its own CSS. Import or copy only the CSS for the plugins you use. See [Plugins](./plugins.md) for the full list including their CSS paths.
-
-## GOV.UK Prototype kit plugin
-
-Following installation the InteractiveMap plugin will be added to your prototype. You can now create pages with a map, and configure for specific use cases.
-
-See [GOV.UK Prototype Kit - Install and use plugins](https://prototype-kit.service.gov.uk/docs/install-and-use-plugins).

package/docs/index.mdx

@@ -26,7 +26,7 @@ import Link from '@docusaurus/Link';
         <h3><Link to="/getting-started" className="govuk-link">Getting Started</Link></h3>
         <p>How to install and configure the component. Covers setup, initialisation options, and integration with common build tools.</p>
         <h3><Link to="/examples" className="govuk-link">Examples</Link></h3>
-        <p>Live interactive demos showing the component in action, including inline maps, button-triggered maps, and various configuration options.</p>
+        <p>Live interactive demos showing the component in action, including basic maps, button-triggered maps, and various configuration options.</p>
         <h3><Link to="/api" className="govuk-link">API Reference</Link></h3>
         <p>Full reference for all configuration options, events, methods, and plugin interfaces exposed by the component.</p>
         <h3><Link to="/plugins" className="govuk-link">Plugins</Link></h3>

package/docs/plugins/interact.md

@@ -50,6 +50,9 @@ Controls which interactions are active when the user clicks the map. Values can
 - `'selectFeature'` — clicking the map attempts to match a feature from `layers`
 - `'placeMarker'` — if no feature is matched (or `selectFeature` is not active), places a location marker at the clicked coordinates
 
+> [!NOTE]
+> On touch and keyboard, a crosshair and "Select" action button are shown when interact is enabled. For touch users, this applies when `'placeMarker'` or `'selectFeature'` is included — modes where a precise point on the map needs to be chosen. When `'selectMarker'` is the only active mode, touch users tap markers directly and the crosshair is not shown.
+
 **Common combinations:**
 
 ```js
@@ -204,7 +207,7 @@ interactPlugin.disable()
 
 ### `clear()`
 
-Clear the current selection or marker.
+Clear all selected features and markers, and remove the location marker.
 
 ```js
 interactPlugin.clear()
@@ -252,6 +255,34 @@ interactPlugin.unselectFeature({
 
 ---
 
+### `selectMarker(markerId)`
+
+Programmatically select a marker. Idempotent — has no effect if the marker is already selected. In single-select mode, clears any selected features and replaces the marker selection. In multi-select mode, adds to the existing selection.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `markerId` | `string` | The ID of the marker to select |
+
+```js
+interactPlugin.selectMarker('my-marker')
+```
+
+---
+
+### `unselectMarker(markerId)`
+
+Programmatically unselect a specific marker. Idempotent — has no effect if the marker is not selected.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `markerId` | `string` | The ID of the marker to unselect |
+
+```js
+interactPlugin.unselectMarker('my-marker')
+```
+
+---
+
 ## Events
 
 Subscribe to events using `interactiveMap.on()`.

package/docs/plugins.md

@@ -10,7 +10,7 @@ The following plugins are available for use with InteractiveMap.
 
 ### [Interact](./plugins/interact.md)
 
-Select features or place markers on the map.
+Select map features, select markers, or place a location marker on the map.
 
 ### [Map Styles](./plugins/map-styles.md)
 

package/docusaurus.config.cjs

@@ -2,7 +2,7 @@
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  staticDirectories: ['assets'],
+  staticDirectories: ['assets', 'docs/assets'],
   title: 'Defra Interactive Map',
   tagline: 'An accessibility-first interactive map component for government frontends',
   favicon: 'images/favicon.svg',
@@ -45,7 +45,7 @@ const config = {
       return {
         name: 'custom-css',
         getClientModules() {
-          return [require.resolve('./assets/css/docusaurus.css')];
+          return [require.resolve('./docs/assets/css/docusaurus.css')];
         },
       };
     },
@@ -79,12 +79,21 @@ const config = {
           href: '/getting-started',
           sidebar: [
             { text: 'Installation', href: '/getting-started#installation' },
+            { text: 'GOV.UK Prototype kit', href: '/getting-started#govuk-prototype-kit' },
+            { text: 'Manual setup', href: '/getting-started#manual-setup' },
             { text: 'Basic usage', href: '/getting-started#basic-usage' },
-            { text: 'Using plugins', href: '/getting-started#using-plugins' },
-            { text: 'GOV.UK Prototype kit', href: '/getting-started#govuk-prototype-kit-plugin' }
+            { text: 'Using plugins', href: '/getting-started#using-plugins' }
+          ],
+        },
+        {
+          text: 'Examples',
+          href: '/examples',
+          sidebar: [
+            { text: 'Basic map', href: '/examples/basic-map' },
+            { text: 'Button-triggered map', href: '/examples/button-map' },
+            { text: 'Add a marker with a panel', href: '/examples/add-marker-with-panel' },
           ],
         },
-        { text: 'Examples', href: '/examples', sidebar: 'auto' },
         {
           text: 'API',
           href: '/api',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/interactive-map",
-  "version": "0.0.18-alpha",
+  "version": "0.0.20-alpha",
   "description": "An accessible map component",
   "repository": {
     "type": "git",
@@ -127,7 +127,7 @@
     "@babel/plugin-transform-runtime": "^7.29.0",
     "@babel/preset-env": "^7.28.0",
     "@babel/preset-react": "^7.27.1",
-    "@defra/docusaurus-theme-govuk": "^0.0.16-alpha",
+    "@defra/docusaurus-theme-govuk": "^0.0.18-alpha",
     "@docusaurus/core": "^3.9.2",
     "@docusaurus/module-type-aliases": "^3.9.2",
     "@docusaurus/plugin-content-docs": "^3.9.2",
@@ -218,7 +218,7 @@
     "@turf/polygon-to-line": "^7.3.3",
     "accessible-autocomplete": "^3.0.1",
     "govuk-frontend": "^5.13.0",
-    "maplibre-gl": "^5.21.1",
+    "maplibre-gl": "^5.23.0",
     "polygon-splitter": "^0.0.11",
     "preact": "^10.27.2",
     "tslib": "^2.8.1"