@defra/interactive-map 0.0.3-alpha → 0.0.5-alpha

package/docs/plugins/plugin-descriptor.md

@@ -0,0 +1,71 @@
+# PluginDescriptor
+
+Descriptor for lazy-loading a plugin.
+
+## Creating a Plugin Descriptor
+
+Plugins typically export a factory function that returns a PluginDescriptor. This pattern allows configuration to be passed when registering the plugin:
+
+```js
+// scale-bar/index.js
+export default function createPlugin ({ units = 'metric' } = {}) {
+  return {
+    id: 'scaleBar',
+    units,
+    load: async () => {
+      const { manifest } = await import('./manifest.js')
+      return manifest
+    }
+  }
+}
+```
+
+Any properties passed to the factory (except `id` and `load`) are available as [pluginConfig](./plugin-context.md#pluginconfig) within the plugin:
+
+```js
+// Registering the plugin with configuration
+import createScaleBarPlugin from '@defra/interactive-map-plugin-scale-bar'
+
+const interactiveMap = new InteractiveMap({
+  plugins: [
+    createScaleBarPlugin({ units: 'imperial' })
+  ]
+})
+```
+
+```js
+// Accessing configuration within the plugin
+export function ScaleBar ({ mapState, pluginConfig }) {
+  const { units } = pluginConfig
+  // ...
+}
+```
+
+## Properties
+
+---
+
+### `id`
+**Type:** `string`
+**Required**
+
+Unique plugin identifier.
+
+---
+
+### `load`
+**Type:** `function`
+**Required**
+
+Async function that loads and returns a [PluginManifest](./plugin-manifest.md).
+
+```ts
+() => Promise<PluginManifest>
+```
+
+---
+
+### `manifest`
+**Type:** `Partial<PluginManifest>`
+
+Optional manifest overrides. Allows overriding properties of the loaded [PluginManifest](./plugin-manifest.md).

package/docs/plugins/plugin-manifest.md

@@ -0,0 +1,118 @@
+# PluginManifest
+
+Manifest defining a plugin's buttons, panels, controls, icons, API methods, and state.
+
+## Properties
+
+---
+
+### `api`
+**Type:** `Object`
+
+Public methods exposed by the plugin for external use. These methods can be called via the plugin instance:
+
+```js
+myPlugin.doSomething()
+```
+
+Each function receives a [PluginContext](./plugin-context.md) as its first argument, providing access to app state, map provider, services, and more. Additional arguments follow.
+
+```js
+{
+  doSomething: (context) => {
+    console.log(context.appState.breakpoint)
+  },
+  getValue: (context, id) => {
+    return context.pluginState[id]
+  }
+}
+```
+
+---
+
+### `buttons`
+**Type:** `ButtonDefinition[]`
+
+Button definitions to register in the UI.
+
+Buttons come with pre-built behaviour and styling, including icon support, labels, tooltips, and pressed states. Supports responsive breakpoint configuration.
+
+See [ButtonDefinition](../api/button-definition.md) for full details.
+
+---
+
+### `controls`
+**Type:** `ControlDefinition[]`
+
+Custom control definitions to register in the UI.
+
+Use controls for bespoke UI elements that don't fit the button or panel pattern. Controls have no pre-built behaviour or styling—you have full control over rendering and interaction. Supports responsive breakpoint configuration.
+
+See [ControlDefinition](../api/control-definition.md) for full details.
+
+---
+
+### `icons`
+**Type:** `IconDefinition[]`
+
+Icon definitions to register in the icon registry.
+
+The icon registry is a singleton shared across all map instances and plugins. Registering an icon with an existing ID will override it. This enforces visual consistency across the application, including when multiple map instances exist on the same page.
+
+See [IconDefinition](../api/icon-definition.md) for full details.
+
+---
+
+### `InitComponent`
+**Type:** `ComponentType`
+
+A React/Preact component rendered when the plugin loads. Use this for initialisation logic, side effects, or rendering hidden UI elements.
+
+- Mounted once when the app loads
+- Re-renders when [PluginContext](./plugin-context.md) state changes (e.g., `appState`, `pluginState`, `mapState`)
+- Typically returns `null` if no visible UI is needed
+
+```jsx
+const InitComponent = ({ context }) => {
+  const { appState, mapProvider, pluginState } = context
+
+  useEffect(() => {
+    // Run side effects when state changes
+    console.log('Breakpoint:', appState.breakpoint)
+  }, [appState.breakpoint])
+
+  return null
+}
+```
+
+---
+
+### `panels`
+**Type:** `PanelDefinition[]`
+
+Panel definitions to register in the UI.
+
+Panels come with pre-built behaviour and styling, including headings, dismissable states, and modal overlays. Supports responsive breakpoint configuration.
+
+See [PanelDefinition](../api/panel-definition.md) for full details.
+
+---
+
+### `reducer`
+**Type:** `Object`
+
+Reducer configuration for plugin state management.
+
+```js
+{
+  initialState: {
+    isActive: false
+  },
+  actions: {
+    setActive: (state, isActive) => ({
+      ...state,
+      isActive
+    })
+  }
+}
+```

package/docs/plugins/scale-bar.md

@@ -0,0 +1,62 @@
+# Scale Bar Plugin
+
+Displays the current map scale. The scale bar automatically updates as the user zooms in and out.
+
+## Usage
+
+```js
+import createScaleBarPlugin from '@defra/interactive-map/plugins/scale-bar'
+
+const scaleBarPlugin = createScaleBarPlugin({
+  units: 'metric'
+})
+
+const interactiveMap = new InteractiveMap({
+  plugins: [scaleBarPlugin]
+})
+```
+
+## Options
+
+Options are passed to the factory function when creating the plugin.
+
+---
+
+### `units`
+**Type:** `'metric' | 'imperial'`
+**Default:** `'metric'`
+
+The unit system used to display the scale.
+
+| Value | Description |
+|-------|-------------|
+| `'metric'` | Displays scale in metres and kilometres |
+| `'imperial'` | Displays scale in feet and miles |
+
+```js
+createScaleBarPlugin({ units: 'imperial' })
+```
+
+---
+
+### `includeModes`
+**Type:** `string[]`
+
+Array of mode identifiers. When set, the plugin only renders when the app is in one of these modes.
+
+---
+
+### `excludeModes`
+**Type:** `string[]`
+
+Array of mode identifiers. When set, the plugin does not render when the app is in one of these modes.
+
+---
+
+## Methods
+
+This plugin does not expose any public methods.
+
+## Events
+
+This plugin does not emit any custom events.

package/docs/plugins/search.md

@@ -0,0 +1,162 @@
+# Search Plugin
+
+Location search plugin with autocomplete functionality. Supports custom datasets for searching locations, addresses, or other geographic features.
+
+## Usage
+
+```js
+import createSearchPlugin from '@defra/interactive-map/plugins/search'
+
+const searchPlugin = createSearchPlugin({
+  showMarker: true,
+  datasets: [
+    {
+      id: 'os-places',
+      url: '/api/search',
+      minChars: 3
+    }
+  ]
+})
+
+const interactiveMap = new InteractiveMap({
+  plugins: [searchPlugin]
+})
+```
+
+## Options
+
+Options are passed to the factory function when creating the plugin.
+
+---
+
+### `showMarker`
+**Type:** `boolean`
+**Default:** `true`
+
+Whether to display a marker at the selected location.
+
+---
+
+### `datasets`
+**Type:** `SearchDataset[]`
+
+Array of dataset configurations for search. Each dataset defines a source for search suggestions.
+
+```js
+createSearchPlugin({
+  datasets: [
+    {
+      id: 'os-places',
+      url: '/api/os-places/search',
+      minChars: 3,
+      params: {
+        maxResults: 10
+      }
+    }
+  ]
+})
+```
+
+---
+
+### `isExpanded`
+**Type:** `boolean`
+**Default:** `false`
+
+Whether the search input is initially expanded on mobile devices.
+
+---
+
+### `markerColor`
+**Type:** `string`
+
+Colour of the search result marker. Overrides the default `markerColor` option.
+
+---
+
+### `includeModes`
+**Type:** `string[]`
+
+Array of mode identifiers. When set, the plugin only renders when the app is in one of these modes.
+
+---
+
+### `excludeModes`
+**Type:** `string[]`
+
+Array of mode identifiers. When set, the plugin does not render when the app is in one of these modes.
+
+---
+
+## Methods
+
+This plugin does not expose any public methods.
+
+## Events
+
+Subscribe to events using `interactiveMap.on()`.
+
+---
+
+### `search:match`
+
+Emitted when a search result is selected.
+
+**Payload:**
+```js
+{
+  query: 'London',
+  text: 'London, Greater London',
+  point: [lng, lat],
+  bounds: [west, south, east, north]
+}
+```
+
+```js
+interactiveMap.on('search:match', ({ query, point, bounds }) => {
+  console.log('Location selected:', query)
+  console.log('Coordinates:', point)
+})
+```
+
+---
+
+### `search:open`
+
+Emitted when the search input is expanded (mobile only).
+
+**Payload:** None
+
+```js
+interactiveMap.on('search:open', () => {
+  console.log('Search opened')
+})
+```
+
+---
+
+### `search:close`
+
+Emitted when the search input is collapsed or dismissed.
+
+**Payload:** None
+
+```js
+interactiveMap.on('search:close', () => {
+  console.log('Search closed')
+})
+```
+
+---
+
+### `search:clear`
+
+Emitted when the search input is cleared.
+
+**Payload:** None
+
+```js
+interactiveMap.on('search:clear', () => {
+  console.log('Search cleared')
+})
+```

package/docs/plugins.md

@@ -0,0 +1,116 @@
+# Plugins
+
+Plugins extend the InteractiveMap with additional functionality. This page lists the available plugins and links to their documentation.
+
+For guidance on building your own plugins, see [Building a Plugin](./building-a-plugin.md).
+
+## Available Plugins
+
+The following plugins are available for use with InteractiveMap.
+
+### [Interact](./plugins/interact.md)
+
+Select features or place markers on the map.
+
+### [Map Styles](./plugins/map-styles.md)
+
+Map style switching plugin that adds a UI control for changing the basemap appearance and the map size (provider depending).
+
+### [Scale Bar](./plugins/scale-bar.md)
+
+Scale bar display plugin that shows the current map scale.
+
+### [Search](./plugins/search.md)
+
+Location search plugin with autocomplete functionality. Include custom datasets to search.
+
+## Alpha Plugins
+
+The following plugins are in early development. APIs and features may change.
+
+### Datasets
+
+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 for ESRI SDK
+
+Draw polygons using the Esri map provider.
+
+### Frame
+
+Add a regular shaped frame to the map and control its position. Use to generate reports or draw features.
+
+### Use Location
+
+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
+
+Plugins are registered via the `plugins` option when creating an InteractiveMap. Plugins typically export a factory function that accepts configuration options:
+
+```js
+import createHighlightPlugin from '@example/highlight-plugin'
+
+const highlightPlugin = createHighlightPlugin({
+  color: '#ff0000',
+  opacity: 0.5
+})
+
+const interactiveMap = new InteractiveMap({
+  // ... other options
+  plugins: [highlightPlugin]
+})
+```
+
+The factory function returns a [PluginDescriptor](./plugins/plugin-descriptor.md) with:
+
+- **id** - Unique identifier for the plugin instance
+- **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
+
+Plugins can emit events that you can listen to using `interactiveMap.on()`:
+
+```js
+interactiveMap.on('highlight:added', ({ id, coords }) => {
+  console.log('Highlight added:', id)
+})
+
+interactiveMap.on('highlight:removed', ({ id }) => {
+  console.log('Highlight removed:', id)
+})
+```
+
+## Plugin Methods
+
+Plugins can expose methods that you call on the plugin instance:
+
+```js
+// After map:ready, call methods on the plugin instance
+interactiveMap.on('map:ready', () => {
+  highlightPlugin.add('area-1', [[0, 0], [1, 0], [1, 1], [0, 1]])
+  highlightPlugin.remove('area-1')
+})
+```
+
+See individual plugin documentation for available events and methods.
+
+## Further Reading
+
+- [Building a Plugin](./building-a-plugin.md) - Guide to creating custom plugins
+- [PluginDescriptor](./plugins/plugin-descriptor.md) - Plugin registration reference
+- [PluginManifest](./plugins/plugin-manifest.md) - Plugin manifest reference
+- [PluginContext](./plugins/plugin-context.md) - Context available to plugin code

package/govuk-prototype-kit.config.json

@@ -11,14 +11,14 @@
     "/dist/css/",
     "/dist/umd/",
     "/providers/maplibre/dist",
-    "/providers/open-names/dist",
-    "/plugins/datasets/dist",
+    "/providers/beta/open-names/dist",
+    "/plugins/beta/datasets/dist",
     "/plugins/interact/dist",
-    "/plugins/map-styles/dist",
-    "/plugins/scale-bar/dist",
+    "/plugins/beta/map-styles/dist",
+    "/plugins/beta/scale-bar/dist",
     "/plugins/search/dist",
-    "/plugins/use-location/dist",
-    "/plugins/draw-ml/dist",
-    "/plugins/frame/dist"
+    "/plugins/beta/use-location/dist",
+    "/plugins/beta/draw-ml/dist",
+    "/plugins/beta/frame/dist"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/interactive-map",
-  "version": "0.0.3-alpha",
+  "version": "0.0.5-alpha",
   "description": "An accessible map component",
   "main": "dist/umd/index.js",
   "module": "dist/esm/index.js",
@@ -61,6 +61,7 @@
     "@mapbox/mapbox-gl-draw": "^1.5.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
+    "@types/geojson": "^7946.0.16",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "babel-loader": "^10.0.0",
@@ -72,17 +73,19 @@
     "express-static-gzip": "^3.0.0",
     "geodesy": "^2.4.0",
     "html-webpack-plugin": "^5.6.3",
+    "install": "^0.13.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^30.0.4",
     "mapbox-gl-snap": "^1.1.9",
     "mini-css-extract-plugin": "^2.9.2",
     "node-fetch": "^3.3.2",
+    "npm": "^11.8.0",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.6.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "remove-files-webpack-plugin": "^1.5.0",
-    "resize-observer": "^1.0.4",
+    "resize-observer-polyfill": "^1.5.1",
     "rimraf": "^6.1.0",
     "sass": "^1.89.2",
     "sass-loader": "^16.0.5",
@@ -107,15 +110,26 @@
   ],
   "author": "",
   "license": "",
+  "overrides": {
+    "@turf/bearing": "^7.3.3"
+  },
   "dependencies": {
     "@arcgis/core": "^4.34.8",
     "@turf/area": "^7.2.0",
+    "@turf/bearing": "^7.3.3",
+    "@turf/boolean-disjoint": "^7.3.3",
     "@turf/boolean-valid": "^7.2.0",
+    "@turf/destination": "^7.3.3",
     "@turf/helpers": "^7.2.0",
+    "@turf/line-intersect": "^7.3.3",
+    "@turf/point-to-line-distance": "^7.3.3",
+    "@turf/polygon-to-line": "^7.3.3",
+    "abortcontroller-polyfill": "^1.7.8",
     "core-js": "^3.44.0",
     "govuk-frontend": "^5.13.0",
     "maplibre-gl": "^5.15.0",
     "maplibre-gl-legacy": "npm:maplibre-gl@1.15.3",
+    "polygon-splitter": "^0.0.11",
     "preact": "^10.27.2"
   }
 }