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

package/docs/architecture.md

@@ -0,0 +1,139 @@
+# Architecture Overview 
+
+This framework is a **web mapping platform** designed to let teams add interactive maps to public-facing services in a consistent, extensible, and framework-agnostic way. 
+
+At its core, it provides: 
+* A stable map UI with consistent behaviour 
+* A plugin system for extending functionality 
+* An abstraction layer over multiple mapping engines 
+
+The system is designed so that **the core controls rendering and layout**, while **plugins declaratively contribute behaviour and UI.** ---
+
+## High-level Structure 
+
+The framework consists of five main parts: 
+1. **Public API** (Vanilla JS wrapper) 
+2. **Core React component**
+3. **Map provider abstraction**
+4. **Plugin system**
+5. **Rendering and slot system** 
+
+---
+
+## 1. Public API (Vanilla JS wrapper) 
+
+The framework is consumed via a **vanilla JavaScript API**, making it easy to integrate into a wide range of environments (including legacy stacks and non-React applications).
+
+This wrapper:
+
+* **Instantiates** the core component  
+* **Passes** configuration, plugins, and providers  
+* **Exposes** events and methods to the host application  
+
+> **Note:** Internally, the UI is implemented in React, but this is an implementation detail and not required knowledge for consumers. 
+
+---
+
+## 2. Core Component 
+
+The core component is the orchestrator of the application. It: 
+* Owns application state 
+* Controls rendering and layout 
+* Provides consistent map interactions (search, identify, draw, pan, etc.) 
+* Manages plugins, providers, and UI composition 
+
+**Stability Guarantee:** Plugins never control the render lifecycle. The core always mounts and renders independently of plugin success or failure. 
+
+---
+
+## 3. Map Provider Abstraction 
+
+The framework is **not tied to a specific mapping library.** It uses a `mapProvider` interface defining semantic operations such as: 
+* Fitting the map to bounds 
+* Setting the view zoom and centre 
+* Querying features 
+
+This allows providers to be swapped without rewriting plugins or UI code.
+
+### MapLibre (Recommended)
+
+Our reference provider, offering the most complete and tested experience:
+
+<table>
+  <tr>
+    <td><strong>Out of the box</strong></td>
+    <td>Works immediately with no additional</td>
+  </tr>
+  <tr>
+    <td><strong>Modern and lightweight</strong></td>
+    <td>Better performance with smaller bundle  sizes</td>
+  </tr>
+  <tr>
+    <td><strong>Vector tile support</strong></td>
+    <td>Most comprehensive support for vector tiles</td>
+  </tr>
+  <tr>
+    <td><strong>Enhanced accessibility</strong></td>
+    <td>The most accessbile offering</td>
+  </tr>
+</table>
+
+### Esri (Experimental)
+An alternative provider with specific advantages:
+
+<table>
+  <tr>
+    <td><strong>British National Grid</strong></td>
+    <td>Native support for BNG coordinate systems</td>
+  </tr>
+</table>
+
+## 4. Plugin System 
+
+### Declarative by Design 
+Plugins describe what they add using a **manifest** (buttons, panels, shortcuts). They are contributors, not "render owners."
+
+### Registration vs Rendering 
+* **Registration:** Reads manifests and populates central registries at load time.
+* **Rendering:** Controlled entirely by the core, which decides where and how items appear based on current state. 
+
+### Isolation 
+Each plugin receives a **ring-fenced slice of state**. They have read access to `appState`, `mapState`, `appConfig`, and `services` (eventBus, geocoding, etc.). 
+
+---
+
+## 5. Rendering and Slot System 
+
+The UI uses a **slot-based system**. Slots represent logical areas (e.g., actions, side panels, modals). 
+
+Plugins declare UI elements with layout hints (which slot to use, modal vs non-modal, mobile vs desktop behavior). The core evaluates these rules to guarantee: 
+* Consistent layout and accessibility 
+* Centralized responsive design 
+* UI stability (plugins cannot "block" the interface) 
+
+---
+
+## Event Bus 
+
+Provides two-way, decoupled communication between the core, plugins, and the vanilla JS layer. This allows external applications to react to internal state changes without tight coupling. 
+
+## Mental Model for Developers 
+
+|||
+| :--- | :--- |
+| **Core** | The Platform |
+| **Plugins** | Declarative Feature Descriptions |
+| **Providers** | Adapters for Map Engines |
+| **Slots** | Layout Positions |
+| **State** | Shared Context |
+
+## Tech stack
+
+|||
+| :--- | :--- |
+| **React** | UI component framework |
+| **MapLibre** | Primary mapping engine |
+| **Webpack** | Module bundling (UMD, ESM builds) |
+| **Jest** | Testing framework |
+| **SCSS** | Styling |
+| **Babel** | JavaScript compilation |

package/docs/building-a-plugin.md

@@ -0,0 +1,149 @@
+# Building Plugins
+
+Plugins extend the InteractiveMap with custom buttons, panels, controls, and behaviours. This guide introduces the plugin system and links to the detailed reference documentation.
+
+## Overview
+
+A plugin is a module that registers UI elements and logic with the map. Plugins can:
+
+- Add **buttons** to the toolbar with built-in styling and behaviour
+- Add **panels** for content like search results or layer controls
+- Add **controls** for fully custom UI elements
+- Register **icons** for use across the application
+- Expose **API methods** callable from outside the plugin
+- Manage **state** with a reducer pattern
+
+## How Plugins Work
+
+A plugin consists of two parts:
+
+1. **Factory function** - Exports a function that accepts configuration and returns a [PluginDescriptor](./plugins/plugin-descriptor.md)
+2. **Manifest** - Defines the plugin's buttons, panels, controls, and other elements
+
+```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
+    }
+  }
+}
+```
+
+The factory pattern allows configuration to be passed when registering the plugin. All properties (except `id` and `load`) are available as [pluginConfig](./plugins/plugin-context.md#pluginconfig) within the plugin.
+
+```js
+import createScaleBarPlugin from '@defra/interactive-map-plugin-scale-bar'
+
+const interactiveMap = new InteractiveMap({
+  // ... other options
+  plugins: [
+    createScaleBarPlugin({ units: 'imperial' })
+  ]
+})
+```
+
+When the map initialises, it calls each plugin's `load` function and registers the manifest's buttons, panels, controls, and other elements.
+
+## Plugin Context
+
+Plugin components and callbacks receive a [PluginContext](./plugins/plugin-context.md) object providing access to:
+
+- **appConfig** - Application configuration
+- **appState** - Current app state (breakpoint, interface type, etc.)
+- **mapState** - Current map state (zoom, center, bounds)
+- **mapProvider** - Methods to interact with the map
+- **pluginConfig** - Configuration passed to the factory function
+- **pluginState** - Plugin-specific state from your reducer
+- **services** - Core services (announcements, reverse geocoding, event bus)
+
+## Quick Example
+
+The scale-bar plugin displays the current map scale. It accepts a `units` option to configure the display format.
+
+```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
+    }
+  }
+}
+```
+
+```js
+// scale-bar/manifest.js
+import { ScaleBar } from './ScaleBar.jsx'
+
+export const manifest = {
+  controls: [{
+    id: 'scaleBar',
+    label: 'Scale bar',
+    mobile: { slot: 'footer-right' },
+    tablet: { slot: 'footer-right' },
+    desktop: { slot: 'footer-right' },
+    render: ScaleBar
+  }]
+}
+```
+
+```jsx
+// scale-bar/ScaleBar.jsx
+export function ScaleBar ({ mapState, pluginConfig }) {
+  const { resolution } = mapState
+  const { units } = pluginConfig
+
+  // Calculate scale based on resolution and units
+  const scale = calculateScale(resolution, units)
+
+  return (
+    <div className="scale-bar">
+      {scale.label}
+    </div>
+  )
+}
+```
+
+```js
+// Usage
+import createScaleBarPlugin from '@defra/interactive-map-plugin-scale-bar'
+
+const interactiveMap = new InteractiveMap({
+  plugins: [
+    createScaleBarPlugin({ units: 'imperial' })
+  ]
+})
+```
+
+## Reference Documentation
+
+For detailed specifications, see:
+
+- [PluginDescriptor](./plugins/plugin-descriptor.md) - How to register a plugin
+- [PluginManifest](./plugins/plugin-manifest.md) - What a plugin can contain
+- [PluginContext](./plugins/plugin-context.md) - Context available to plugin code
+- [ButtonDefinition](./api/button-definition.md) - Button configuration
+- [PanelDefinition](./api/panel-definition.md) - Panel configuration
+- [ControlDefinition](./api/control-definition.md) - Custom control configuration
+- [IconDefinition](./api/icon-definition.md) - Icon registration
+- [Slots](./api/slots.md) - UI slot system for positioning elements
+
+## Events
+
+Plugins can subscribe to application and map events via the `eventBus` service. See the [Events](./api.md#events) section in the API reference for available events.
+
+```js
+const { eventBus, events } = context.services
+
+eventBus.on(events.APP_PANEL_OPENED, ({ panelId }) => {
+  console.log('Panel opened:', panelId)
+})
+```

package/docs/getting-started.md

@@ -0,0 +1,46 @@
+# Getting started
+
+## Installation
+
+Run:
+
+```shell
+npm i @defra/interactive-map
+```
+
+## Use in production
+
+In your html, you will need to add a container element for the map:
+
+```html
+<div id="map"></div>
+```
+
+You will need to initialise and configure InteractiveMap in your client side code:
+
+```js
+import InteractiveMap from '@defra/interactive-map'
+import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+
+const interactiveMap = new InteractiveMap('map', {
+  mapProvider: 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'
+  }
+})
+```
+
+## 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 [Install and use plugins](https://prototype-kit.service.gov.uk/docs/install-and-use-plugins).
+
+See [Configuring InteractiveMap in a GOVUK Prototype](./docs/govuk-prototype).

package/docs/plugins/interact.md

@@ -0,0 +1,205 @@
+# Interact Plugin
+
+Select features or place markers on the map. The interact plugin provides a unified way to handle user interactions for selecting map features or placing location markers.
+
+## Usage
+
+```js
+import createInteractPlugin from '@defra/interactive-map/plugins/interact'
+
+const interactPlugin = createInteractPlugin()
+
+const interactiveMap = new InteractiveMap({
+  plugins: [interactPlugin]
+})
+```
+
+## Options
+
+Options are passed to the factory function when creating the plugin.
+
+---
+
+### `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
+
+Methods are called on the plugin instance after the map is ready.
+
+---
+
+### `enable()`
+
+Enable interaction mode. Shows action buttons and enables feature selection or marker placement.
+
+```js
+interactiveMap.on('map:ready', () => {
+  interactPlugin.enable()
+})
+```
+
+---
+
+### `disable()`
+
+Disable interaction mode. Hides action buttons and disables interactions.
+
+```js
+interactPlugin.disable()
+```
+
+---
+
+### `clear()`
+
+Clear the current selection or marker.
+
+```js
+interactPlugin.clear()
+```
+
+---
+
+### `selectFeature(feature)`
+
+Programmatically select a feature.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `feature` | `Object` | Feature object to select |
+
+```js
+interactPlugin.selectFeature({ id: 'feature-1', bounds: [...] })
+```
+
+---
+
+### `unselectFeature()`
+
+Clear the currently selected feature.
+
+```js
+interactPlugin.unselectFeature()
+```
+
+---
+
+## Events
+
+Subscribe to events using `interactiveMap.on()`.
+
+---
+
+### `interact:done`
+
+Emitted when the user confirms their selection (clicks "Done").
+
+**Payload:**
+```js
+{
+  marker: { coords: [lng, lat] } | null,
+  selection: { bounds: [...], feature: {...} } | null
+}
+```
+
+```js
+interactiveMap.on('interact:done', ({ marker, selection }) => {
+  if (marker) {
+    console.log('Location selected:', marker.coords)
+  }
+  if (selection) {
+    console.log('Feature selected:', selection.feature)
+  }
+})
+```
+
+---
+
+### `interact:cancel`
+
+Emitted when the user cancels the interaction.
+
+**Payload:** None
+
+```js
+interactiveMap.on('interact:cancel', () => {
+  console.log('Interaction cancelled')
+})
+```
+
+---
+
+### `interact:markerchange`
+
+Emitted when the marker position changes.
+
+**Payload:**
+```js
+{
+  coords: [lng, lat]
+}
+```
+
+```js
+interactiveMap.on('interact:markerchange', ({ coords }) => {
+  console.log('Marker moved to:', coords)
+})
+```
+
+---
+
+### `interact:selectionchange`
+
+Emitted when the feature selection changes.
+
+**Payload:**
+```js
+{
+  bounds: [west, south, east, north],
+  feature: { ... }
+}
+```
+
+```js
+interactiveMap.on('interact:selectionchange', ({ bounds, feature }) => {
+  console.log('Selection changed:', feature)
+})
+```
+
+---
+
+### `interact:selectFeature`
+
+Emitted when a feature is programmatically selected via the API.
+
+**Payload:**
+```js
+{
+  feature: { ... }
+}
+```
+
+---
+
+### `interact:unselectFeature`
+
+Emitted when a feature is programmatically unselected via the API.
+
+**Payload:**
+```js
+{
+  feature: { ... }
+}
+```

package/docs/plugins/map-styles.md

@@ -0,0 +1,84 @@
+# Map Styles Plugin
+
+Map style switching plugin that adds a UI control for changing the basemap appearance and the map size.
+
+## Usage
+
+```js
+import createMapStylesPlugin from '@defra/interactive-map/plugins/map-styles'
+
+const mapStylesPlugin = createMapStylesPlugin({
+  mapStyles: [
+    {
+      id: 'default',
+      label: 'Default',
+      url: '/styles/default.json',
+      thumbnail: '/images/default-thumb.png'
+    },
+    {
+      id: 'satellite',
+      label: 'Satellite',
+      url: '/styles/satellite.json',
+      thumbnail: '/images/satellite-thumb.png'
+    }
+  ]
+})
+
+const interactiveMap = new InteractiveMap({
+  plugins: [mapStylesPlugin]
+})
+```
+
+## Options
+
+Options are passed to the factory function when creating the plugin.
+
+---
+
+### `mapStyles`
+**Type:** `MapStyleConfig[]`
+**Required**
+
+Array of map style configurations. Each style appears as an option in the style switcher UI.
+
+See [MapStyleConfig](../api/map-style-config.md) for full details.
+
+```js
+createMapStylesPlugin({
+  mapStyles: [
+    {
+      id: 'default',
+      label: 'Default',
+      url: '/styles/default.json',
+      appColorScheme: 'light',
+      mapColorScheme: 'light',
+      backgroundColor: '#f5f5f5',
+      thumbnail: '/images/default-thumb.png'
+    }
+  ]
+})
+```
+
+---
+
+### `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. Style changes are handled internally and update the map automatically.

package/docs/plugins/plugin-context.md

@@ -0,0 +1,67 @@
+# PluginContext
+
+Plugin components and callbacks receive the base [Context](../api/context.md) plus the plugin-specific properties documented below.
+
+PluginContext is received by:
+- [InitComponent](./plugin-manifest.md#initcomponent) - as props
+- [API methods](./plugin-manifest.md#api) - as the first argument
+- [Panel render components](./panel-definition.md#render) - as props
+- [Control render components](./control-definition.md#render) - as props
+- [Button callbacks](./button-definition.md) (`onClick`, `enableWhen`, `hiddenWhen`, `excludeWhen`, `pressedWhen`) - as an argument (`onClick` receives event first, context second)
+
+## Base Context Properties
+
+See [Context](../api/context.md) for the following properties available to all contexts:
+
+- `appConfig` - Application configuration
+- `appState` - Current application state
+- `iconRegistry` - Icon registry
+- `mapProvider` - Map provider instance
+- `mapState` - Current map state
+- `services` - Core services
+
+## Plugin-Specific Properties
+
+---
+
+### `pluginConfig`
+**Type:** `Object`
+
+Plugin-specific configuration. Contains all properties from the [PluginDescriptor](./plugin-descriptor.md) except `id` and `load`.
+
+When using the factory function pattern, any options passed to the factory become available here:
+
+```js
+// When registering:
+createScaleBarPlugin({ units: 'imperial' })
+
+// Within the plugin:
+const { units } = context.pluginConfig
+```
+
+See [Creating a Plugin Descriptor](./plugin-descriptor.md#creating-a-plugin-descriptor) for the full pattern.
+
+---
+
+### `pluginState`
+**Type:** `Object`
+
+Plugin-specific state managed by the plugin's reducer, plus utilities for updating state.
+
+```js
+{
+  // State values from your reducer's initialState
+  isActive: false,
+
+  // Dispatch function for updating plugin state
+  dispatch: ({ type, payload }) => { /* ... */ }
+}
+```
+
+```js
+// Access state
+const { isActive } = context.pluginState
+
+// Update state
+context.pluginState.dispatch({ type: 'setActive', payload: true })
+```