@defra/interactive-map 0.0.15-alpha → 0.0.17-alpha

package/docs/plugins/search.md

@@ -1,25 +1,20 @@
 # Search Plugin
 
-Location search plugin with autocomplete functionality. Supports custom datasets for searching locations, addresses, or other geographic features.
+Location search with autocomplete. Supports the OS Names API out of the box, and can be extended with custom datasets for searching addresses, features, or other geographic data.
 
 ## Usage
 
 ```js
-import createSearchPlugin from '@defra/interactive-map/plugins/search'
-
-const searchPlugin = createSearchPlugin({
-  showMarker: true,
-  datasets: [
-    {
-      id: 'os-places',
-      url: '/api/search',
-      minChars: 3
-    }
-  ]
-})
+import searchPlugin from '@defra/interactive-map/plugins/search'
 
 const interactiveMap = new InteractiveMap({
-  plugins: [searchPlugin]
+  plugins: [
+    searchPlugin({
+      osNamesURL: process.env.OS_NAMES_URL,
+      transformRequest: transformGeocodeRequest,
+      showMarker: true
+    })
+  ]
 })
 ```
 
@@ -29,48 +24,94 @@ Options are passed to the factory function when creating the plugin.
 
 ---
 
-### `showMarker`
-**Type:** `boolean`
-**Default:** `true`
+### `osNamesURL`
+**Type:** `string`
 
-Whether to display a marker at the selected location.
+URL for the OS Names API, with a `{query}` placeholder. When provided, the plugin uses this as the primary search source.
+
+```js
+searchPlugin({
+  osNamesURL: 'https://api.os.uk/search/names/v1/find?query={query}&key=YOUR_KEY'
+})
+```
 
 ---
 
-### `datasets`
-**Type:** `SearchDataset[]`
+### `transformRequest`
+**Type:** `Function`
 
-Array of dataset configurations for search. Each dataset defines a source for search suggestions.
+Async function called before each search request is sent. Use this to add authentication headers or modify the request. Receives the default request config and the query string, and should return a (modified) request config.
 
 ```js
-createSearchPlugin({
-  datasets: [
-    {
-      id: 'os-places',
-      url: '/api/os-places/search',
-      minChars: 3,
-      params: {
-        maxResults: 10
-      }
-    }
-  ]
+searchPlugin({
+  transformRequest: async (request, query) => ({
+    ...request,
+    headers: { Authorization: `Bearer ${token}` }
+  })
+})
+```
+
+---
+
+### `regions`
+**Type:** `string[]`
+**Default:** `['england', 'scotland', 'wales']`
+
+Filters OS Names results to the specified UK regions. Values are matched case-insensitively against the country field in OS Names results.
+
+```js
+searchPlugin({
+  regions: ['england', 'wales']
+})
+```
+
+---
+
+### `customDatasets`
+**Type:** `CustomDataset[]`
+
+Array of custom dataset configurations to extend or replace the built-in OS Names search. Each dataset defines how to fetch and parse results for a particular type of query.
+
+See [Custom datasets](#custom-datasets) below for full details.
+
+```js
+searchPlugin({
+  customDatasets: [gridRefDataset, parcelDataset]
 })
 ```
 
 ---
 
-### `isExpanded`
+### `showMarker`
 **Type:** `boolean`
-**Default:** `false`
+**Default:** `true`
 
-Whether the search input is initially expanded on mobile devices.
+Whether to place a marker on the map when a search result is selected.
 
 ---
 
 ### `markerColor`
 **Type:** `string`
 
-Colour of the search result marker. Overrides the default `markerColor` option.
+Colour of the search result marker.
+
+---
+
+### `width`
+**Type:** `string`
+
+CSS width of the search input on tablet and desktop. For example `'300px'`.
+
+---
+
+### `expanded`
+**Type:** `boolean`
+**Default:** `false`
+
+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.
+- **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.
 
 ---
 
@@ -88,10 +129,117 @@ Array of mode identifiers. When set, the plugin does not render when the app is
 
 ---
 
+## Custom datasets
+
+Custom datasets let you add your own search sources alongside or instead of OS Names. Pass them via the `customDatasets` option as an array of dataset configuration objects.
+
+```js
+const gridRefDataset = {
+  name: 'gridref',
+  includeRegex: /^[A-Z]{2}\d{6,10}$/i,
+  buildRequest: (query) => `https://api.example.com/gridref?q=${query}`,
+  parseResults: (json, query) => [{
+    id: query,
+    text: query,
+    marked: `<mark>${query}</mark> (Grid reference)`,
+    point: [json.lon, json.lat],
+    bounds: [json.minLon, json.minLat, json.maxLon, json.maxLat],
+    type: 'gridref'
+  }]
+}
+
+searchPlugin({
+  customDatasets: [gridRefDataset]
+})
+```
+
+### `CustomDataset` properties
+
+---
+
+#### `name`
+**Type:** `string`
+**Required**
+
+Unique identifier for the dataset. Included as the `type` property in the `search:match` event payload, which lets you distinguish between results from different datasets.
+
+---
+
+#### `buildRequest`
+**Type:** `Function`
+
+Function that takes the search query and returns a URL string or a `{ url, options }` fetch config object. Use this when you need custom URL construction or fetch options.
+
+If omitted, `urlTemplate` is used instead.
+
+```js
+buildRequest: (query) => ({
+  url: `https://api.example.com/search?q=${encodeURIComponent(query)}`,
+  options: { headers: { Accept: 'application/json' } }
+})
+```
+
+---
+
+#### `urlTemplate`
+**Type:** `string`
+
+URL template with a `{query}` placeholder. A simpler alternative to `buildRequest` for straightforward GET requests.
+
+```js
+urlTemplate: 'https://api.example.com/search?q={query}'
+```
+
+---
+
+#### `parseResults`
+**Type:** `Function`
+**Required**
+
+Function that receives the parsed JSON response and the original query string, and returns an array of suggestion objects. Return an empty array if there are no results.
+
+Each suggestion object must have:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Unique identifier for the suggestion |
+| `text` | `string` | Display text shown in the autocomplete list |
+| `marked` | `string` | Optional. HTML string with query terms wrapped in `<mark>` tags. If omitted, the suggestion label will be blank |
+| `point` | `[x, y]` | Centre coordinate for placing a marker |
+| `bounds` | `[minX, minY, maxX, maxY]` | Bounding box to fit the map to when selected |
+| `type` | `string` | Optional. Value to include in the `search:match` payload to identify the source dataset |
+
+Any additional properties on the suggestion object are passed through in the `search:match` event payload.
+
+---
+
+#### `includeRegex`
+**Type:** `RegExp`
+
+If provided, the dataset is only queried when the input matches this pattern. Useful for datasets that only apply to specific input formats (e.g. grid references, parcel IDs).
+
+---
+
+#### `excludeRegex`
+**Type:** `RegExp`
+
+If provided, the dataset is skipped when the input matches this pattern.
+
+---
+
+#### `exclusive`
+**Type:** `boolean`
+
+When `true`, if this dataset returns results no other datasets will be queried. Useful for high-confidence lookups where you want to suppress the OS Names fallback.
+
+---
+
 ## Methods
 
 This plugin does not expose any public methods.
 
+---
+
 ## Events
 
 Subscribe to events using `interactiveMap.on()`.
@@ -100,63 +248,59 @@ Subscribe to events using `interactiveMap.on()`.
 
 ### `search:match`
 
-Emitted when a search result is selected.
+Emitted when the user selects a search result.
 
 **Payload:**
+
+The full suggestion object returned by the dataset's `parseResults` function, plus the original `query` string. At minimum:
+
 ```js
 {
-  query: 'London',
-  text: 'London, Greater London',
+  query: 'NY7019',          // The original search input
+  id: '...',
+  text: 'NY 701 924',
+  marked: '<mark>NY 701 924</mark> (Grid reference)',
   point: [lng, lat],
-  bounds: [west, south, east, north]
+  bounds: [west, south, east, north],
+  type: 'gridref'           // The dataset name, useful for distinguishing result types
+  // ...any other properties returned by parseResults
 }
 ```
 
 ```js
-interactiveMap.on('search:match', ({ query, point, bounds }) => {
-  console.log('Location selected:', query)
-  console.log('Coordinates:', point)
+interactiveMap.on('search:match', (e) => {
+  if (e.type === 'parcel') {
+    interactPlugin.selectFeature({ featureId: e.properties.id, layerId: 'parcels' })
+  }
 })
 ```
 
 ---
 
-### `search:open`
+### `search:clear`
 
-Emitted when the search input is expanded (mobile only).
+Emitted when the search input is cleared.
 
 **Payload:** None
 
 ```js
-interactiveMap.on('search:open', () => {
-  console.log('Search opened')
+interactiveMap.on('search:clear', () => {
+  interactPlugin.unselectFeature({ featureId: selectedId })
 })
 ```
 
 ---
 
-### `search:close`
+### `search:open`
 
-Emitted when the search input is collapsed or dismissed.
+Emitted when the open button is clicked to expand the search. Only applies when `expanded` is `false`, as that is the only case where an open button is rendered.
 
 **Payload:** None
 
-```js
-interactiveMap.on('search:close', () => {
-  console.log('Search closed')
-})
-```
-
 ---
 
-### `search:clear`
+### `search:close`
 
-Emitted when the search input is cleared.
+Emitted when the search is dismissed — via the close button, a click outside the search, or (on mobile only) after a suggestion is selected or the form is submitted.
 
 **Payload:** None
-
-```js
-interactiveMap.on('search:clear', () => {
-  console.log('Search cleared')
-})
-```

package/docs/plugins.md

@@ -4,7 +4,7 @@ Plugins extend the InteractiveMap with additional functionality. This page lists
 
 For guidance on building your own plugins, see [Building a Plugin](./building-a-plugin.md).
 
-## Available Plugins
+## Available plugins
 
 The following plugins are available for use with InteractiveMap.
 
@@ -24,17 +24,17 @@ Scale bar display plugin that shows the current map scale.
 
 Location search plugin with autocomplete functionality. Include custom datasets to search.
 
-## Alpha Plugins
+## Coming soon
 
 The following plugins are in early development. APIs and features may change.
 
-### Datasets
+### [Datasets](./plugins/datasets.md)
 
 Add datasets to your map, configure the display, layer toggling and render a key of symbology.
 
 ### Draw for MapLibre
 
-Draw lines and polygons using the MapLibre map provider.
+Draw lines, polygons and place points using the MapLibre map provider. Includes geometry actions such as split and merge.
 
 ### Draw for ESRI SDK
 
@@ -48,15 +48,7 @@ Add a regular shaped frame to the map and control its position. Use to generate
 
 Geolocation plugin that allows users to centre the map on their current location.
 
-## Coming Soon
-
-The following plugins are planned for future releases.
-
-### Geometry Actions
-
-Split and merge polygons.
-
-## Using Plugins
+## Using plugins
 
 Plugins are registered via the `plugins` option when creating an InteractiveMap. Plugins typically export a factory function that accepts configuration options:
 
@@ -80,7 +72,7 @@ The factory function returns a [PluginDescriptor](./plugins/plugin-descriptor.md
 - **load** - Function that returns a [PluginManifest](./plugins/plugin-manifest.md)
 - **...options** - Configuration passed to the factory, available as [pluginConfig](./plugins/plugin-context.md#pluginconfig)
 
-## Plugin Events
+## Plugin events
 
 Plugins can emit events that you can listen to using `interactiveMap.on()`:
 
@@ -94,7 +86,7 @@ interactiveMap.on('highlight:removed', ({ id }) => {
 })
 ```
 
-## Plugin Methods
+## Plugin methods
 
 Plugins can expose methods that you call on the plugin instance:
 
@@ -108,7 +100,7 @@ interactiveMap.on('map:ready', () => {
 
 See individual plugin documentation for available events and methods.
 
-## Further Reading
+## Further reading
 
 - [Building a Plugin](./building-a-plugin.md) - Guide to creating custom plugins
 - [PluginDescriptor](./plugins/plugin-descriptor.md) - Plugin registration reference

package/docusaurus.config.cjs

@@ -3,9 +3,9 @@
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   staticDirectories: ['assets'],
-  title: 'Interactive Map',
+  title: 'Defra Interactive Map',
   tagline: 'An accessibility-first interactive map component for government frontends',
-  favicon: 'images/favicon.ico',
+  favicon: 'images/favicon.svg',
 
   url: 'https://defra.github.io',
   baseUrl: '/interactive-map/',
@@ -41,6 +41,14 @@ const config = {
   ],
 
   plugins: [
+    function customCssPlugin() {
+      return {
+        name: 'custom-css',
+        getClientModules() {
+          return [require.resolve('./assets/css/docusaurus.css')];
+        },
+      };
+    },
     [
       '@docusaurus/plugin-content-docs',
       {
@@ -66,18 +74,17 @@ const config = {
       },
 
       navigation: [
-        { text: 'Getting Started', href: '/getting-started' },
-        { text: 'Demo', href: '/demo', sidebar: 'auto' },
         {
-          text: 'Architecture',
-          href: '/architecture',
+          text: 'Getting Started',
+          href: '/getting-started',
           sidebar: [
-            { text: 'Overview', href: '/architecture' },
-            { text: 'Diagrams', href: 'architecture-diagrams' },
-            { text: 'Diagram Viewer', href: 'diagrams-viewer' },
+            { text: 'Installation', href: '/getting-started#installation' },
+            { 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: 'GOV.UK Prototype', href: '/govuk-prototype' },
+        { text: 'Examples', href: '/examples', sidebar: 'auto' },
         {
           text: 'API',
           href: '/api',
@@ -87,31 +94,24 @@ const config = {
           text: 'Plugins',
           href: '/plugins',
           sidebar: [
-            { text: 'Overview', href: '/plugins' },
-            { text: 'Building a Plugin', href: '/building-a-plugin' },
-            {
-              text: 'Available Plugins',
-              href: '/plugins#available-plugins',
-              items: [
-                { text: 'Interact', href: '/plugins#interact' },
-                { text: 'Map Styles', href: '/plugins#map-styles' },
-                { text: 'Scale Bar', href: '/plugins#scale-bar' },
-                { text: 'Search', href: '/plugins#search' },
-              ],
-            },
-            {
-              text: 'Alpha Plugins',
-              href: '/plugins#alpha-plugins',
-              items: [
-                { text: 'Datasets', href: '/plugins#datasets' },
-                { text: 'Draw for MapLibre', href: '/plugins#draw-for-maplibre' },
-                { text: 'Draw for ESRI SDK', href: '/plugins#draw-for-esri-sdk' },
-                { text: 'Frame', href: '/plugins#frame' },
-                { text: 'Use Location', href: '/plugins#use-location' },
-              ],
-            },
+            // { text: 'Overview', href: '/plugins' },
+            // { text: 'Building a Plugin', href: '/building-a-plugin' },
+            { text: 'Available Plugins', href: '/plugins#available-plugins' },
+            { text: 'Coming soon', href: '/plugins#coming-soon' },
+            { text: 'Using plugins', href: '/plugins#using-plugins' },
+            { text: 'Plugin events', href: '/plugins#plugin-events' },
+            { text: 'Plugin methods', href: '/plugins#plugin-methods' },
+            { text: 'Further reading', href: '/plugins#further-reading' },
           ],
         },
+        {
+          text: 'Architecture',
+          href: '/architecture',
+          sidebar: [
+            { text: 'Diagrams', href: 'architecture-diagrams' },
+            { text: 'Diagram Viewer', href: 'diagrams-viewer' },
+          ],
+        }
       ],
 
       phaseBanner: {
@@ -127,7 +127,7 @@ const config = {
 
       homepage: {
         getStartedHref: '/getting-started',
-        description: 'A lightweight, accessible map component for public-facing government services. Open source, multi-engine, and extendable through plugins.',
+        description: 'Built for developers creating public-facing services on GOV.UK. Takes care of the hard work of building an accessible, standards-compliant mapping interface, so you can focus on your data.',
       },
     },
   },

package/jest.setup.js

@@ -15,4 +15,4 @@ if (!window.matchMedia) {
       dispatchEvent: jest.fn()
     }))
   })
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/interactive-map",
-  "version": "0.0.15-alpha",
+  "version": "0.0.17-alpha",
   "description": "An accessible map component",
   "repository": {
     "type": "git",
@@ -86,10 +86,10 @@
     "build": "npm run clean && npm-run-all --parallel build:umd build:esm",
     "type-check": "tsc --noEmit",
     "lint": "npm run lint:js && npm run lint:scss",
-    "lint:js": "standard \"src/**/*.{js,jsx,ts,tsx}\"",
+    "lint:js": "standard \"./**/*.{js,jsx,ts,tsx}\"",
     "lint:scss": "stylelint \"src/**/*.{css,scss}\"",
     "lint:fix": "npm run lint:js:fix && npm run lint:scss:fix",
-    "lint:js:fix": "standard \"src/**/*.{js,jsx,ts,tsx}\" --fix",
+    "lint:js:fix": "standard \"./**/*.{js,jsx,ts,tsx}\" --fix",
     "lint:scss:fix": "stylelint \"src/**/*.{css,scss}\" --fix",
     "test": "jest --color --coverage --verbose",
     "report": "webpack --profile --json --config webpack.prod.mjs > stats.json && webpack-bundle-analyzer --host 0.0.0.0 --port 8888 ./stats.json ./public",
@@ -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.12-alpha",
+    "@defra/docusaurus-theme-govuk": "^0.0.16-alpha",
     "@docusaurus/core": "^3.9.2",
     "@docusaurus/module-type-aliases": "^3.9.2",
     "@docusaurus/plugin-content-docs": "^3.9.2",
@@ -156,6 +156,7 @@
     "geodesy": "^2.4.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^30.0.4",
+    "jest-expect-message": "^1.1.3",
     "likec4": "^1.50.0",
     "mapbox-gl-snap": "^1.1.9",
     "mini-css-extract-plugin": "^2.9.2",
@@ -217,7 +218,7 @@
     "@turf/polygon-to-line": "^7.3.3",
     "accessible-autocomplete": "^3.0.1",
     "govuk-frontend": "^5.13.0",
-    "maplibre-gl": "^5.15.0",
+    "maplibre-gl": "^5.21.1",
     "polygon-splitter": "^0.0.11",
     "preact": "^10.27.2",
     "tslib": "^2.8.1"