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

package/docs/api.md

@@ -27,18 +27,20 @@ Parameters:
 
 The `id` of a container element where the map will be rendered.
 
+---
+
 ### `options`
 **Type:** `Object`
 
 Configuration object specifying map provider, map style, behaviour, and other settings. See Options below.
 
+> [!NOTE]
+> In addition to the options below, any option supported by your map engine can be passed and will be forwarded to the provider constructor. See your map provider's documentation for available options (e.g., [MapLibre MapOptions](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/)).
+
 ---
 
 ## Options
 
-> [!NOTE]
-> In addition to the options below, any option supported by your map engine can be passed and will be forwarded to the provider constructor. See your map provider's documentation for available options (e.g., [MapLibre MapOptions](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/)).
-
 ---
 
 ### `appColorScheme`
@@ -47,8 +49,6 @@ Configuration object specifying map provider, map style, behaviour, and other se
 
 Colour scheme used by the application. Determines the colours of panels, buttons and controls.
 
-**Possible values**
-
 | Possible values |
 |:--|
 | **'light'** *(default)*
@@ -76,6 +76,18 @@ May be provided as:
 - A single CSS colour value applied to all map styles
 - An object keyed by map style ID, where each value is a valid CSS colour
 
+```js
+// Single value applied to all map styles
+new InteractiveMap('map', {
+  backgroundColor: '#f5f5f0'
+})
+
+// Keyed by map style ID
+new InteractiveMap('map', {
+  backgroundColor: { outdoor: '#f5f5f0', dark: '#383F43' }
+})
+```
+
 ---
 
 ### `behaviour`
@@ -84,16 +96,14 @@ May be provided as:
 
 Determines how and when the map is displayed.
 
-**Possible values**
-
 | Possible values |
 |:--|
 | **'buttonFirst'** *(default)*
-Map is initially hidden and a button is displayed in its place. Selecting the button opens the map in fullscreen mode. The optional `pageTitle` property is appended to the page title. This behaviour minimises resources downloaded when not all users need a map. |
+Map is initially hidden and a button is displayed in its place. Selecting the button opens the map in fullscreen mode. The optional `pageTitle` property is appended to the page title. This provides a less intrusive experience for users who do not need or cannot use the map. It also minimises resources downloaded for services where the map is not central. |
 | **'inline'**
 The map is rendered inline with the body content and initially visible. |
 | **'hybrid'**
-A combination of button and inline behaviour, controlled by the optional `hybridWidth`. At smaller sizes a button is displayed; at larger sizes the map is rendered inline. When fullscreen, the optional `pageTitle` property is appended to the page title. |
+A combination of buttonFirst and inline behaviour, controlled by the optional `hybridWidth`. At smaller sizes a button is displayed; at larger sizes the map is rendered inline. When fullscreen, the optional `pageTitle` property is appended to the page title. |
 | **'mapOnly'**
 Renders the map fullscreen on all devices, using the existing page title. |
 
@@ -129,7 +139,7 @@ The button is only displayed when the `behaviour` is `hybrid` or `buttonFirst`.
 ### `center`
 **Type:** `[number, number]`
 
-Initial center [lng, lat] or [easting, northing] depending on the crs of the map provider.
+Initial centre [lng, lat] or [easting, northing] depending on the crs of the map provider.
 
 Passed directly to the underlying map engine.
 
@@ -139,7 +149,7 @@ Passed directly to the underlying map engine.
 **Type:** `string`
 **Default:** `'600px'`
 
-CSS height applied to the map container when the map is `inline`.
+CSS height applied to the map container. Only used when the map is rendered inline; ignored when displayed fullscreen.
 
 ---
 
@@ -155,16 +165,16 @@ Message displayed when the user's device or browser is not supported.
 **Default:** `false`
 
 Whether a toggle button is displayed to allow the map to enter fullscreen mode.
-The button is only displayed when the map is `inline`.
+The button is only displayed when the map is rendered inline.
 
 ---
 
 ### `enableZoomControls`
 **Type:** `boolean`
-**Default:** `false`
+**Default:** `true`
 
 Whether zoom control buttons are displayed.
-Zoom controls are not diplayed when the interface type is `touch`.
+Zoom controls are not displayed when the interface type is 'touch'.
 
 ---
 
@@ -189,7 +199,7 @@ Fallback error message shown when the map fails to load.
 **Default:** `false`
 
 Whether an exit button is displayed.
-The exit button is only displayed when the behavour is `buttonFirst` or `hybrid` and the map is `fullscreen`.
+The exit button is only displayed when the behaviour is `buttonFirst` or `hybrid` and the map is displayed fullscreen.
 
 ---
 
@@ -197,7 +207,7 @@ The exit button is only displayed when the behavour is `buttonFirst` or `hybrid`
 **Type:** `number | null`
 **Default:** `null`
 
-Optional viewport width breakpoint (in pixels) used by the `'hybrid'` behaviour.
+Optional viewport width breakpoint (in pixels) used by the `hybrid` behaviour.
 When not set, defaults to `maxMobileWidth`.
 
 ---
@@ -205,8 +215,10 @@ When not set, defaults to `maxMobileWidth`.
 ### `keyboardHintText`
 **Type:** `string`
 
-HTML string providing keyboard shortcut instructions for assistive technology users.
-The hint text is displayed as a popup label when the `viewport` has focus.
+HTML string shown as a tooltip on the viewport when it receives keyboard focus, prompting the user to open the keyboard shortcuts modal.
+
+> [!NOTE]
+> It is unlikely you will need to override this. If you do, keep the text short to avoid breaking the layout of the tooltip.
 
 ---
 
@@ -214,8 +226,13 @@ The hint text is displayed as a popup label when the `viewport` has focus.
 **Type:** `string`
 **Required**
 
-Accessible label describing the purpose of the map.
-This value is announced to screen readers.
+Accessible name for the map viewport, which has a role of `application`. This label is announced by screen readers when the viewport receives focus and should describe the purpose of the map.
+
+```js
+new InteractiveMap('map', {
+  mapLabel: 'Flood risk areas in England'
+})
+```
 
 ---
 
@@ -223,7 +240,13 @@ This value is announced to screen readers.
 **Type:** `function`
 **Required**
 
-A factory function that returns a map provider instance, e.g., `maplibreProvider()`.
+A function that returns a map provider — the abstraction layer that interfaces with the underlying map engine. It is called only when the map is opened so the provider code is not sent to the user unless needed.
+
+```js
+new InteractiveMap('map', {
+  mapProvider: maplibreProvider()
+})
+```
 
 ---
 
@@ -233,8 +256,6 @@ A factory function that returns a map provider instance, e.g., `maplibreProvider
 
 Visual size of text and features in the map itself.
 
-**Possible values**
-
 | Possible values |
 |:--|
 | **'small'** *(default)*
@@ -260,7 +281,7 @@ See [MapStyleConfig](./api/map-style-config.md) for full details.
 **Type:** `string`
 **Default:** `'mv'`
 
-URL query parameter key used to persist map visibility state.
+URL query parameter key used to persist map visibility state. Override if the default value clashes with an existing parameter on your page.
 
 ---
 
@@ -276,9 +297,9 @@ See [MarkerConfig](./api/marker-config.md) for full details.
 ### `symbolDefaults`
 **Type:** `Partial<SymbolDefaults>`
 
-App-wide defaults for symbol and marker appearance. These values apply across all markers and datasets unless a more specific value is set at the symbol or per-marker level. Any property omitted here falls back to the built-in default:
+App-wide defaults for symbol and marker appearance.
 
-| Property | Built-in default |
+| Property | Default |
 |---|---|
 | `symbol` | `'pin'` |
 | `backgroundColor` | `'#ca3535'` |
@@ -302,7 +323,7 @@ See [Symbol Config](./api/symbol-config.md) for the full property list.
 ### `maxExtent`
 **Type:** `[number, number, number, number]`
 
-Maximum viewable extent [west, south, east, north]. Passed directly to the map engine; implementation varies.
+Maximum viewable extent [west, south, east, north]. Passed directly to the underlying map engine; how it is enforced depends on the provider.
 
 ---
 
@@ -370,7 +391,7 @@ Smaller zoom increment used for fine-grained zoom adjustments.
 **Type:** `string`
 
 Supplementary text appended to the existing page title.
-Only used when the beahviour is `buttonFirst` or `hybrid` and the map is displayed in `fullscreen` mode.
+Only used when the behaviour is `buttonFirst` or `hybrid` and the map is displayed fullscreen.
 
 ---
 
@@ -385,7 +406,7 @@ Distance (in pixels) the map pans during standard pan interactions.
 ### `plugins`
 **Type:** `PluginDescriptor[]`
 
-Plugins to load.
+Optional extensions that add features such as datasets, search, or custom panels to the map.
 
 See [PluginDescriptor](./plugins/plugin-descriptor.md) for full details.
 
@@ -395,7 +416,7 @@ See [PluginDescriptor](./plugins/plugin-descriptor.md) for full details.
 **Type:** `boolean`  
 **Default:** `false`  
 
-Controls whether closing the map (via the browser back button or the exit map button when `hasExitButton` is `true` and the map is fullscreen) destroys the map instance or hides it while preserving its current state. Set to `true` to keep the map state intact, which is useful for implementations like a toggle map view list view pattern.
+Controls whether closing the map destroys the map instance or hides it while preserving its current state. When `true`, state is retained between open and close — for example in a map/list toggle, a user can interact with the map, switch to the list view, then reopen the map and pick up exactly where they left off.
 
 ---
 
@@ -405,22 +426,28 @@ Controls whether closing the map (via the browser back button or the exit map bu
 
 Whether map text labels can be selected and read aloud by assistive technologies.
 
-> [!WARNING]
-> **Experimental:** This is a development flag. It currently only works with MapLibre and specific styles. Do **not** enable in production unless fully tested.
+> [!CAUTION]
+> This is experimental. It currently only works with MapLibre and specific styles. Do **not** enable in production unless fully tested.
 
 ---
 
 ### `reverseGeocodeProvider`
 **Type:** `function | null`
 
-A factory function that returns a reverse geocode provider instance, e.g., `openNamesProvider()`.
+A function that returns a reverse geocode provider used to convert map coordinates to a place name, for example when announcing the current map position to screen reader users. Like the map provider, it is only called when the map is opened so the provider code is not sent to the user unless needed.
+
+```js
+new InteractiveMap('map', {
+  reverseGeocodeProvider: openNamesProvider()
+})
+```
 
 ---
 
 ### `transformRequest`
 **Type:** `function`
 
-Function to transform outgoing requests (e.g., to add authentication headers). Passed directly to MapLibre; other map engines may have their own equivalent. For ESRI SDK, this is handled in the EsriMapProvider configuration.
+Function to transform outgoing requests, for example to add authentication headers. This option is specific to MapLibre and is passed directly to the underlying MapLibre instance.
 
 ```js
 (url, resourceType) => { url, headers, credentials }
@@ -429,7 +456,7 @@ Function to transform outgoing requests (e.g., to add authentication headers). P
 See the [MapLibre documentation](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/RequestParameters/) for full details.
 
 > [!NOTE]
-> This function is synchronous. For asynchronous authentication flows such as OAuth, consider alternative approaches like overriding the fetch prototype. Further guidance to follow.
+> For ESRI SDK, request transformation is handled in the EsriMapProvider configuration rather than through this option.
 
 ---
 
@@ -488,7 +515,9 @@ Add a marker to the map.
 |-----------|------|-------------|
 | `id` | `string` | Unique marker identifier |
 | `coords` | `[number, number]` | Coordinates [lng, lat] or [easting, northing] depending on CRS |
-| `options` | [`MarkerOptions`](./api/marker-config.md#markeroptions) | Optional marker appearance options |
+| `options` | `MarkerOptions` | Optional marker appearance options |
+
+See [MarkerOptions](./api/marker-config.md#markeroptions) for configuration options.
 
 ```js
 interactiveMap.addMarker('home', [-0.1276, 51.5074], { backgroundColor: '#1d70b8' })
@@ -550,14 +579,14 @@ interactiveMap.addButton('my-menu', {
 
 ### `addPanel(id, config)`
 
-Add a panel to the UI at runtime.
+Adds a new panel with content to the UI at runtime. Focus is moved to the panel by default — set `focus: false` in the config to suppress this when adding panels on page load.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `id` | `string` | Unique panel identifier |
 | `config` | `PanelDefinition` | Panel configuration |
 
-See [PanelDefinition](./api/panel-definition.md) for configuration options. When using this method, provide content via the `html` property.
+See [PanelDefinition](./api/panel-definition.md) for all configuration options.
 
 ```js
 interactiveMap.addPanel('info-panel', {
@@ -573,7 +602,7 @@ interactiveMap.addPanel('info-panel', {
 
 ### `removePanel(id)`
 
-Remove a panel from the UI.
+Removes a panel from the UI entirely. Use `hidePanel` instead if you want to show it again later.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -585,23 +614,27 @@ interactiveMap.removePanel('info-panel')
 
 ---
 
-### `showPanel(id)`
+### `showPanel(id, options?)`
 
-Show a panel.
+Shows a panel that already exists but is hidden. Focus is moved to the panel by default — set `focus: false` to suppress this, useful when you want focus to remain on the triggering button.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `id` | `string` | Panel identifier to show |
+| `options.focus` | `boolean` | Whether to move focus to the panel. Default: `true` |
 
 ```js
 interactiveMap.showPanel('info-panel')
+
+// Keep focus on the triggering button
+interactiveMap.showPanel('info-panel', { focus: false })
 ```
 
 ---
 
 ### `hidePanel(id)`
 
-Hide a panel.
+Hides a panel without removing it, preserving its content for when it is shown again.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -628,7 +661,7 @@ See [ControlDefinition](./api/control-definition.md) for configuration options.
 
 ### `setMode(mode)`
 
-Set the application mode.
+Programmatically set the application mode. See the [`mode`](#mode) option for more detail.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -642,7 +675,7 @@ interactiveMap.setMode('fullscreen')
 
 ### `toggleButtonState(id, prop, value)`
 
-Set or toggle a button state.
+Set or toggle a button state. Where applicable the corresponding ARIA attribute is updated — `aria-pressed`, `aria-disabled`, or `aria-expanded`.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -698,15 +731,15 @@ interactiveMap.fitToBounds({
 
 ---
 
-### `setView(opts)`
+### `setView(options)`
 
 Set the map center and zoom. Safe zone padding is automatically applied.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `opts` | `Object` | View options |
-| `opts.center` | `[number, number]` | Optional center [lng, lat] or [easting, northing] depending on CRS |
-| `opts.zoom` | `number` | Optional zoom level |
+| `options` | `Object` | View options |
+| `options.center` | `[number, number]` | Optional center [lng, lat] or [easting, northing] depending on CRS |
+| `options.zoom` | `number` | Optional zoom level |
 
 ```js
 interactiveMap.setView({ center: [-0.1276, 51.5074], zoom: 12 })
@@ -714,6 +747,26 @@ interactiveMap.setView({ center: [-0.1276, 51.5074], zoom: 12 })
 
 ---
 
+### `open()`
+
+Programmatically open the map. Equivalent to the user clicking the open button. If the map has been hidden (e.g. in hybrid mode), it will be shown; otherwise the app will be loaded for the first time.
+
+```js
+interactiveMap.open()
+```
+
+---
+
+### `close()`
+
+Programmatically close the map. Triggers the same logic as the exit button. If `preserveStateOnClose` is `true`, the map is hidden but not destroyed; otherwise the app is removed entirely.
+
+```js
+interactiveMap.close()
+```
+
+---
+
 ## Events
 
 Subscribe to events using `interactiveMap.on()` and unsubscribe with `interactiveMap.off()`.

package/docs/architecture.md

@@ -32,8 +32,6 @@ This wrapper:
 * **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 

package/docs/assets/css/docusaurus.css

@@ -0,0 +1,205 @@
+/* Custom styles for the Interactive Map docs site */
+
+.app-section {
+  padding: 40px 0;
+  background-color: #ffffff;
+}
+
+.govuk-template__body.app-homepage .govuk-template__body-inner {
+  background-color: #f4f8fb;
+}
+
+.app-section--features {
+  background-color: #f4f8fb;
+  border-bottom: 1px solid #8eb8dc;
+}
+
+.app-prose-scope .app-section--features p:not(.app-no-prose *) {
+  margin-bottom: 0;
+}
+
+.app-section--features .govuk-grid-column-one-third:not(:first-child) {
+  margin-top: 30px;
+
+  @media (min-width: 48.125em) {
+    margin-top: 0;
+  }
+}
+
+/* Hero image */
+.govuk-template--rebranded .app-masthead .govuk-grid-row {
+  @media (min-width: 48.125em) {
+    display: flex;
+  }
+}
+
+.govuk-template--rebranded .app-masthead .govuk-grid-column-one-third-from-desktop {
+  @media (min-width: 48.125em) {
+    background-image: url('/images/hero.png');
+    background-repeat: no-repeat;
+    background-position: center bottom;
+    background-size: 220px;
+  }
+}
+
+/* Color 100% */
+.govuk-template--rebranded .app-masthead .govuk-button--inverse,
+.govuk-template--rebranded .app-masthead .govuk-button--inverse:visited,
+.govuk-template--rebranded .app-masthead .govuk-button--inverse:active,
+.govuk-template--rebranded .app-masthead .govuk-button--inverse:hover {
+  color: #008531;
+}
+
+/* Background colour 100% */
+.govuk-template--rebranded .govuk-header__link--homepage:not(:focus),
+.govuk-template--rebranded .govuk-header,
+.govuk-template--rebranded .govuk-service-navigation.govuk-service-navigation--inverse,
+.govuk-template--rebranded .app-masthead {
+  background-color: #008531 !important;
+}
+
+/* Box shadow colur #083d29 */
+.govuk-template--rebranded .app-masthead .govuk-button--inverse {
+  box-shadow: 0 2px 0 #0b5c3e;
+}
+
+/* Border colour 50% tint */
+.govuk-template--rebranded .app-homepage .govuk-service-navigation--inverse .govuk-width-container {
+  border-color: #66B683 !important;
+}
+
+/* Example apps */
+.app-example {
+  margin-bottom: 20px;
+}
+
+/* Example index cards */
+.app-example-card {
+  position: relative;
+  margin-bottom: 30px;
+  border: 1px solid #b1b4b6;
+}
+
+.app-example-card > img {
+  display: block;
+  width: 100%;
+}
+
+.app-example-card__body {
+  padding: 15px;
+}
+
+.app-prose-scope *:not(.app-no-prose *) .app-example-card__body h2:last-child {
+  margin-bottom: 0;
+}
+
+.app-example-card__body .govuk-heading-m {
+  margin-bottom: 0;
+}
+
+.app-example-card .govuk-heading-m a::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+}
+
+/* Fix sticky footer: the theme gives flex: 1 0 auto to any govuk-width-container
+   that is a direct child of govuk-template__body-inner, but the phase banner div
+   also matches that selector and grows incorrectly on short pages. Move the
+   flex-grow to <main> instead so only the content area stretches. */
+.govuk-template--rebranded .govuk-template__body-inner > .govuk-width-container {
+  flex: none;
+}
+
+.govuk-template--rebranded .govuk-main-wrapper {
+  flex: 1 0 auto;
+}
+
+/* GOV.UK tabs — enhanced styles for all devices; React manages active state.
+   Extra specificity via .app-prose-scope required to override the theme. */
+.govuk-tabs {
+  margin-top: 5px;
+  margin-bottom: 40px;
+  font-size: 1.1875rem;
+  line-height: 1.3157894737;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__list {
+  overflow: hidden;
+  margin: 0;
+  padding: 5px 0 0;
+  list-style: none;
+  border-bottom: 1px solid #b1b4b6;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__list-item {
+  position: relative;
+  float: left;
+  margin: 0 5px 0 0;
+  padding: 10px 20px;
+  background-color: #f3f2f1;
+  text-align: center;
+}
+
+.app-prose-scope .govuk-tabs__list-item::before {
+  content: none;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__list-item--selected {
+  margin-top: -5px;
+  padding: 14px 19px 15px;
+  border: 1px solid #b1b4b6;
+  border-bottom: 0;
+  background-color: #ffffff;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__tab {
+  display: inline-block;
+  margin-bottom: 0;
+  text-decoration: underline;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__tab:is(:link, :visited, :hover, :active) {
+  color: #0b0c0c;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__list-item--selected .govuk-tabs__tab {
+  text-decoration: none;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__tab::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__panel {
+  padding: 0;
+  border: 1px solid #b1b4b6;
+  border-top: 0;
+  margin-bottom: 0;
+}
+
+.app-prose-scope .govuk-tabs .govuk-tabs__panel > :last-child {
+  margin-bottom: 0;
+}
+
+.app-prose-scope .govuk-tabs__panel--hidden {
+  display: none;
+}
+
+.app-prose-scope .govuk-tabs .app-code-block__pre {
+  margin: 0;
+}
+
+/* Heading overides */
+.app-prose-scope *:not(.app-no-prose *) .govuk-heading-l {
+    font-size: 2.25rem;
+    line-height: 1.1111111111;
+}
+
+.app-prose-scope *:not(.app-no-prose *) .govuk-heading-m {
+  font-size: 1.5rem;
+  line-height: 1.25;
+  margin-bottom: 20px;
+}