@defra/interactive-map 0.0.30-alpha → 0.0.32-alpha

package/docs/examples/draw-tools.mdx

@@ -0,0 +1,271 @@
+import DemoMapDrawTools from '../../demo/DemoMapDrawTools.js'
+import CodeTabs from '../../demo/js/codeTabs.js'
+
+# Draw tools
+
+Draw, edit, select and delete polygons and lines using the draw and interact plugins. A single "Draw tools" menu button groups all drawing actions together. The menu items update their enabled state based on whether a drawn feature is selected.
+
+:::note
+The draw plugin (`draw-ml`) is currently in beta.
+:::
+
+<DemoMapDrawTools />
+
+<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'
+      import createDrawPlugin from '@defra/interactive-map/plugins/draw-ml'
+
+      const DRAW_LAYERS = ['fill-inactive.cold', 'stroke-inactive.cold']
+
+      const interactPlugin = createInteractPlugin({
+        layers: [
+          { layerId: 'fill-inactive.cold', idProperty: 'id' },
+          { layerId: 'stroke-inactive.cold', idProperty: 'id' }
+        ],
+        interactionModes: ['selectFeature'],
+        multiSelect: true,
+        deselectOnClickOutside: true
+      })
+
+      const drawPlugin = createDrawPlugin()
+
+      const interactiveMap = new InteractiveMap('my-map', {
+        behaviour: 'inline',
+        mapProvider: maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-0.1276, 51.5074],
+        zoom: 12,
+        containerHeight: '516px',
+        plugins: [interactPlugin, drawPlugin]
+      })
+
+      let selectedFeatureIds = []
+
+      interactiveMap.on('map:ready', () => {
+        interactPlugin.enable()
+
+        interactiveMap.addButton('drawTools', {
+          label: 'Draw tools',
+          mobile: { slot: 'bottom-right' },
+          tablet: { slot: 'top-middle' },
+          desktop: { slot: 'top-middle' },
+          menuItems: [
+            {
+              id: 'drawPolygon',
+              label: 'Draw polygon',
+              iconSvgContent: '<path d="M19.5 7v10M4.5 7v10M7 19.5h10M7 4.5h10"/><path d="M22 18v3a1 1 0 0 1-1 1h-3a1 1 0 0 1-1-1v-3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1zm0-15v3a1 1 0 0 1-1 1h-3a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1zM7 18v3a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1v-3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1zM7 3v3a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1z"/>',
+              onClick: () => {
+                interactiveMap.toggleButtonState('drawTools', 'hidden', true)
+                drawPlugin.newPolygon(crypto.randomUUID())
+              }
+            },
+            {
+              id: 'drawLine',
+              label: 'Draw line',
+              iconSvgContent: '<path d="M5.706 16.294L16.294 5.706"/><path d="M21 2v3c0 .549-.451 1-1 1h-3c-.549 0-1-.451-1-1V2c0-.549.451-1 1-1h3c.549 0 1 .451 1 1zM6 17v3c0 .549-.451 1-1 1H2c-.549 0-1-.451-1-1v-3c0-.549.451-1 1-1h3c.549 0 1 .451 1 1z"/>',
+              onClick: () => {
+                interactiveMap.toggleButtonState('drawTools', 'hidden', true)
+                drawPlugin.newLine(crypto.randomUUID())
+              }
+            },
+            {
+              id: 'editFeature',
+              label: 'Edit feature',
+              iconSvgContent: '<path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/>',
+              isDisabled: true,
+              onClick: () => {
+                if (!drawPlugin.editFeature(selectedFeatureIds[0])) return
+                interactiveMap.toggleButtonState('drawTools', 'hidden', true)
+                interactPlugin.disable()
+              }
+            },
+            {
+              id: 'deleteFeature',
+              label: 'Delete feature',
+              iconSvgContent: '<path d="M10 11v6"/><path d="M14 11v6"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M3 6h18"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/>',
+              isDisabled: true,
+              onClick: () => {
+                drawPlugin.deleteFeature(selectedFeatureIds)
+                interactPlugin.clear()
+                interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+                interactiveMap.toggleButtonState('drawPolygon', 'disabled', false)
+                interactiveMap.toggleButtonState('drawLine', 'disabled', false)
+                interactiveMap.toggleButtonState('editFeature', 'disabled', true)
+                interactiveMap.toggleButtonState('deleteFeature', 'disabled', true)
+              }
+            }
+          ]
+        })
+      })
+
+      interactiveMap.on('draw:started', () => {
+        interactPlugin.disable()
+      })
+
+      interactiveMap.on('draw:created', () => {
+        interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+        interactPlugin.enable()
+      })
+
+      interactiveMap.on('draw:edited', () => {
+        interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+        interactPlugin.enable()
+      })
+
+      interactiveMap.on('draw:cancelled', () => {
+        interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+        interactPlugin.enable()
+      })
+
+      interactiveMap.on('interact:selectionchange', (e) => {
+        const singleFeature = e.selectedFeatures.length === 1
+        const anyFeature = e.selectedFeatures.length > 0
+        const isDrawFeature = singleFeature && DRAW_LAYERS.includes(e.selectedFeatures[0].layerId)
+        const allDrawFeatures = anyFeature && e.selectedFeatures.every(f => DRAW_LAYERS.includes(f.layerId))
+        selectedFeatureIds = e.selectedFeatures.map(f => f.featureId)
+        interactiveMap.toggleButtonState('drawPolygon', 'disabled', singleFeature)
+        interactiveMap.toggleButtonState('drawLine', 'disabled', singleFeature)
+        interactiveMap.toggleButtonState('editFeature', 'disabled', !isDrawFeature)
+        interactiveMap.toggleButtonState('deleteFeature', 'disabled', !allDrawFeatures)
+      })
+    `
+  },
+  {
+    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 src="/your-assets-path/draw-ml-plugin/index.js"></script>
+
+      <script>
+      const DRAW_LAYERS = ['fill-inactive.cold', 'stroke-inactive.cold']
+
+      const interactPlugin = defra.interactPlugin({
+        layers: [
+          { layerId: 'fill-inactive.cold', idProperty: 'id' },
+          { layerId: 'stroke-inactive.cold', idProperty: 'id' }
+        ],
+        interactionModes: ['selectFeature'],
+        multiSelect: true,
+        deselectOnClickOutside: true
+      })
+
+      const drawPlugin = defra.drawMLPlugin()
+
+      const interactiveMap = new defra.InteractiveMap('my-map', {
+        behaviour: 'inline',
+        mapProvider: defra.maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-0.1276, 51.5074],
+        zoom: 12,
+        containerHeight: '516px',
+        plugins: [interactPlugin, drawPlugin]
+      })
+
+      let selectedFeatureIds = []
+
+      interactiveMap.on('map:ready', function () {
+        interactPlugin.enable()
+
+        interactiveMap.addButton('drawTools', {
+          label: 'Draw tools',
+          mobile: { slot: 'bottom-right' },
+          tablet: { slot: 'top-middle' },
+          desktop: { slot: 'top-middle' },
+          menuItems: [
+            {
+              id: 'drawPolygon',
+              label: 'Draw polygon',
+              iconSvgContent: '<path d="M19.5 7v10M4.5 7v10M7 19.5h10M7 4.5h10"/><path d="M22 18v3a1 1 0 0 1-1 1h-3a1 1 0 0 1-1-1v-3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1zm0-15v3a1 1 0 0 1-1 1h-3a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1zM7 18v3a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1v-3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1zM7 3v3a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1z"/>',
+              onClick: function () {
+                interactiveMap.toggleButtonState('drawTools', 'hidden', true)
+                drawPlugin.newPolygon(crypto.randomUUID())
+              }
+            },
+            {
+              id: 'drawLine',
+              label: 'Draw line',
+              iconSvgContent: '<path d="M5.706 16.294L16.294 5.706"/><path d="M21 2v3c0 .549-.451 1-1 1h-3c-.549 0-1-.451-1-1V2c0-.549.451-1 1-1h3c.549 0 1 .451 1 1zM6 17v3c0 .549-.451 1-1 1H2c-.549 0-1-.451-1-1v-3c0-.549.451-1 1-1h3c.549 0 1 .451 1 1z"/>',
+              onClick: function () {
+                interactiveMap.toggleButtonState('drawTools', 'hidden', true)
+                drawPlugin.newLine(crypto.randomUUID())
+              }
+            },
+            {
+              id: 'editFeature',
+              label: 'Edit feature',
+              iconSvgContent: '<path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/>',
+              isDisabled: true,
+              onClick: function () {
+                if (!drawPlugin.editFeature(selectedFeatureIds[0])) return
+                interactiveMap.toggleButtonState('drawTools', 'hidden', true)
+                interactPlugin.disable()
+              }
+            },
+            {
+              id: 'deleteFeature',
+              label: 'Delete feature',
+              iconSvgContent: '<path d="M10 11v6"/><path d="M14 11v6"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M3 6h18"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/>',
+              isDisabled: true,
+              onClick: function () {
+                drawPlugin.deleteFeature(selectedFeatureIds)
+                interactPlugin.clear()
+                interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+                interactiveMap.toggleButtonState('drawPolygon', 'disabled', false)
+                interactiveMap.toggleButtonState('drawLine', 'disabled', false)
+                interactiveMap.toggleButtonState('editFeature', 'disabled', true)
+                interactiveMap.toggleButtonState('deleteFeature', 'disabled', true)
+              }
+            }
+          ]
+        })
+      })
+
+      interactiveMap.on('draw:started', function () {
+        interactPlugin.disable()
+      })
+
+      interactiveMap.on('draw:created', function () {
+        interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+        interactPlugin.enable()
+      })
+
+      interactiveMap.on('draw:edited', function () {
+        interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+        interactPlugin.enable()
+      })
+
+      interactiveMap.on('draw:cancelled', function () {
+        interactiveMap.toggleButtonState('drawTools', 'hidden', false)
+        interactPlugin.enable()
+      })
+
+      interactiveMap.on('interact:selectionchange', function (e) {
+        var singleFeature = e.selectedFeatures.length === 1
+        var anyFeature = e.selectedFeatures.length > 0
+        var isDrawFeature = singleFeature && DRAW_LAYERS.includes(e.selectedFeatures[0].layerId)
+        var allDrawFeatures = anyFeature && e.selectedFeatures.every(function (f) { return DRAW_LAYERS.includes(f.layerId) })
+        selectedFeatureIds = e.selectedFeatures.map(function (f) { return f.featureId })
+        interactiveMap.toggleButtonState('drawPolygon', 'disabled', singleFeature)
+        interactiveMap.toggleButtonState('drawLine', 'disabled', singleFeature)
+        interactiveMap.toggleButtonState('editFeature', 'disabled', !isDrawFeature)
+        interactiveMap.toggleButtonState('deleteFeature', 'disabled', !allDrawFeatures)
+      })
+      </script>
+    `
+  }
+]} />

package/docs/examples/index.mdx

@@ -2,52 +2,136 @@ 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'
+import placeMarkerImg from '../assets/images/place-marker.jpg'
 import toggleMarkerLabelImg from '../assets/images/toggle-marker-label.jpg'
+import searchImg from '../assets/images/search.jpg'
+import selectFeatureImg from '../assets/images/select-feature.jpg'
+import styleSwitcherImg from '../assets/images/style-switcher.jpg'
+import drawImg from '../assets/images/draw.jpg'
+import addSymbolsImg from '../assets/images/add-symbols.jpg'
+import addPolygonsImg from '../assets/images/add-polygons.jpg'
 
 export function ExampleCards() {
   const basicHref = useBaseUrl('/examples/basic-map')
   const buttonHref = useBaseUrl('/examples/button-map')
   const interactHref = useBaseUrl('/examples/add-marker-with-panel')
   const toggleMarkerLabelHref = useBaseUrl('/examples/toggle-marker-label')
+  const searchControlHref = useBaseUrl('/examples/search-control')
+  const selectFeatureHref = useBaseUrl('/examples/select-feature')
+  const styleSwitcherHref = useBaseUrl('/examples/style-switcher')
+  const drawHref = useBaseUrl('/examples/draw-tools')
+  const placeMarkerHref = useBaseUrl('/examples/place-marker')
+  const datasetsHref = useBaseUrl('/examples/add-symbols')
+  const polygonsHref = useBaseUrl('/examples/add-polygons')
 
   return (
-    <div className='govuk-grid-row'>
-      <div className='govuk-grid-column-one-half'>
+    <div className='govuk-grid-row app-example-cards'>
+      <div className='govuk-grid-column-one-third'>
         <div className='app-example-card'>
           <img src={basicMapImg} alt='' />
           <div className='app-example-card__body'>
-            <h2 className='govuk-heading-m'>
+            <h2 className='govuk-heading-s'>
               <a href={basicHref}>Basic map</a>
             </h2>
           </div>
         </div>
       </div>
-      <div className='govuk-grid-column-one-half'>
+      <div className='govuk-grid-column-one-third'>
         <div className='app-example-card'>
           <img src={buttonFirstImg} alt='' />
           <div className='app-example-card__body'>
-            <h2 className='govuk-heading-m'>
+            <h2 className='govuk-heading-s'>
               <a href={buttonHref}>Button-triggered map</a>
             </h2>
           </div>
         </div>
       </div>
-      <div className='govuk-grid-column-one-half'>
+      <div className='govuk-grid-column-one-third'>
         <div className='app-example-card'>
           <img src={markerPanelImg} alt='' />
           <div className='app-example-card__body'>
-            <h2 className='govuk-heading-m'>
-              <a href={interactHref}>Add a marker with a panel</a>
+            <h2 className='govuk-heading-s'>
+              <a href={interactHref}>Map with marker and panel</a>
             </h2>
           </div>
         </div>
       </div>
-      <div className='govuk-grid-column-one-half'>
+      <div className='govuk-grid-column-one-third'>
         <div className='app-example-card'>
           <img src={toggleMarkerLabelImg} alt='' />
           <div className='app-example-card__body'>
-            <h2 className='govuk-heading-m'>
-              <a href={toggleMarkerLabelHref}>Toggle marker label on click</a>
+            <h2 className='govuk-heading-s'>
+              <a href={toggleMarkerLabelHref}>Toggle marker label</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={placeMarkerImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={placeMarkerHref}>Place a marker to continue</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={searchImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={searchControlHref}>Add a search control</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={selectFeatureImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={selectFeatureHref}>Select a feature</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={styleSwitcherImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={styleSwitcherHref}>Change map style</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={drawImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={drawHref}>Draw tools</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={addSymbolsImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={datasetsHref}>Add symbols</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-third'>
+        <div className='app-example-card'>
+          <img src={addPolygonsImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-s'>
+              <a href={polygonsHref}>Add polygons</a>
             </h2>
           </div>
         </div>

package/docs/examples/place-marker.mdx

@@ -0,0 +1,151 @@
+import DemoMapPlaceMarker from '../../demo/DemoMapPlaceMarker.js'
+import CodeTabs from '../../demo/js/codeTabs.js'
+
+# Place a marker to continue
+
+Use the interact plugin's `placeMarker` mode to let users drop a location pin on the map before continuing a journey.
+
+Two patterns work together in this example:
+
+- **Hybrid behaviour with built-in back and continue** — on mobile the map opens fullscreen and the `backAndContinue` option renders Back and Continue buttons inside the map. The Continue button is enabled declaratively via `continueEnabledWhen` once a marker has been placed.
+- **External Continue button for inline** — when the map is inline (tablet/desktop), a Continue button sits outside the map container. It uses `app:opened`, `app:closed`, and `app:fullscreenchange` to show and hide in sync with the map's display mode, and `interact:markerchange` to enable once a marker is placed.
+
+<DemoMapPlaceMarker />
+
+<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({
+        interactionModes: ['placeMarker']
+      })
+
+      const map = new InteractiveMap('my-map', {
+        behaviour: 'hybrid',
+        mapProvider: maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-0.1276, 51.5074],
+        zoom: 12,
+        containerHeight: '516px',
+        plugins: [interactPlugin],
+        // Back and Continue buttons shown inside the map when fullscreen (mobile)
+        backAndContinue: {
+          backLabel: 'Back',
+          continueLabel: 'Continue',
+          continueEnabledWhen: ({ mapState }) =>
+            mapState.markers.items.some(m => m.id === 'location')
+        }
+      })
+
+      map.on('map:ready', () => {
+        interactPlugin.enable()
+      })
+
+      // Fired when the built-in Continue button is clicked (mobile/fullscreen)
+      map.on('app:continue', ({ mapState }) => {
+        const marker = mapState.markers.items.find(m => m.id === 'location')
+        // navigate to next step with marker.coords
+      })
+
+      // --- External Continue button for inline (tablet/desktop) ---
+
+      const continueBtn = document.getElementById('continue-btn')
+      const externalButtons = document.getElementById('external-buttons')
+
+      // Show/hide external buttons based on whether the map is inline or fullscreen.
+      // app:opened fires on first load and when the map is shown after being hidden.
+      // app:fullscreenchange fires when the viewport resizes while the map is already visible.
+      const setInline = (isFullscreen) => {
+        externalButtons.hidden = isFullscreen
+      }
+
+      map.on('app:opened', ({ isFullscreen }) => { setInline(isFullscreen) })
+      map.on('app:closed', () => { externalButtons.hidden = true })
+      map.on('app:fullscreenchange', ({ isFullscreen }) => { setInline(isFullscreen) })
+
+      map.on('interact:markerchange', () => {
+        continueBtn.disabled = false
+      })
+
+      continueBtn.addEventListener('click', () => {
+        // navigate to next step
+      })
+    `
+  },
+  {
+    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>
+
+      <div id="my-map"></div>
+      <div id="external-buttons" hidden>
+        <button class="govuk-button" id="continue-btn" disabled>Continue</button>
+      </div>
+
+      <script>
+      var interactPlugin = defra.interactPlugin({
+        interactionModes: ['placeMarker']
+      })
+
+      var map = new defra.InteractiveMap('my-map', {
+        behaviour: 'hybrid',
+        mapProvider: defra.maplibreProvider(),
+        mapStyle: {
+          url: 'https://your-tile-url/style.json',
+          attribution: 'Your tile attribution'
+        },
+        center: [-0.1276, 51.5074],
+        zoom: 12,
+        containerHeight: '516px',
+        plugins: [interactPlugin],
+        backAndContinue: {
+          backLabel: 'Back',
+          continueLabel: 'Continue',
+          continueEnabledWhen: function (context) {
+            return context.mapState.markers.items.some(function (m) { return m.id === 'location' })
+          }
+        }
+      })
+
+      map.on('map:ready', function () {
+        interactPlugin.enable()
+      })
+
+      map.on('app:continue', function (context) {
+        var marker = context.mapState.markers.items.find(function (m) { return m.id === 'location' })
+        // navigate to next step with marker.coords
+      })
+
+      var continueBtn = document.getElementById('continue-btn')
+      var externalButtons = document.getElementById('external-buttons')
+
+      function setInline(isFullscreen) {
+        externalButtons.hidden = isFullscreen
+      }
+
+      map.on('app:opened', function (e) { setInline(e.isFullscreen) })
+      map.on('app:closed', function () { externalButtons.hidden = true })
+      map.on('app:fullscreenchange', function (e) { setInline(e.isFullscreen) })
+
+      map.on('interact:markerchange', function () {
+        continueBtn.disabled = false
+      })
+
+      continueBtn.addEventListener('click', function () {
+        // navigate to next step
+      })
+      </script>
+    `
+  }
+]} />

package/docs/examples/search-control.mdx

@@ -0,0 +1,71 @@
+import DemoMapSearchNominatim from '../../demo/DemoMapSearchNominatim.js'
+import CodeTabs from '../../demo/js/codeTabs.js'
+
+# Add a search control
+
+Add a search control using the built-in OS Names API integration.
+
+:::note
+The live demo below uses Nominatim (no API key required) — the code example uses OS Names, so results may differ slightly. Embedding the key in the URL is the simplest approach for prototyping; for production, `transformRequest` can be used to inject auth headers, or you may need to route requests through your own server-side proxy.
+:::
+
+<DemoMapSearchNominatim />
+
+<CodeTabs tabs={[
+  {
+    label: 'ESM',
+    language: 'js',
+    code: `
+      import InteractiveMap from '@defra/interactive-map'
+      import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+      import createSearchPlugin from '@defra/interactive-map/plugins/search'
+
+      const searchPlugin = createSearchPlugin({
+        osNamesURL: 'https://api.os.uk/search/names/v1/find?query={query}&key=YOUR_API_KEY',
+        width: '300px'
+      })
+
+      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: '516px',
+        plugins: [searchPlugin]
+      })
+    `
+  },
+  {
+    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/search-plugin/index.js"></script>
+
+      <script>
+      const searchPlugin = defra.searchPlugin({
+        osNamesURL: 'https://api.os.uk/search/names/v1/find?query={query}&key=YOUR_API_KEY',
+        width: '300px'
+      })
+
+      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: '516px',
+        plugins: [searchPlugin]
+      })
+      </script>
+    `
+  }
+]} />