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

package/docs/api/symbol-registry.md

@@ -0,0 +1,115 @@
+# Symbol Registry
+
+The symbol registry is a service that manages reusable named symbols for map markers. It is available to plugin authors via `services.symbolRegistry`.
+
+> **Application code** that needs a one-off custom marker should pass [`symbolSvgContent`](./symbol-config.md#symbolsvgcontent) directly to `addMarker()` via `MarkerOptions` instead — no registration required.
+
+## Built-in symbols
+
+Two symbols are registered by default:
+
+| ID | Anchor | Description |
+|----|--------|-------------|
+| `'pin'` | `[0.5, 1]` | Teardrop pin — tip aligns with the coordinate |
+| `'circle'` | `[0.5, 0.5]` | Filled circle — centre aligns with the coordinate |
+
+Both use the standard `{{token}}` placeholders and respect the resolution order described in [Symbol Config](./symbol-config.md#how-values-are-resolved).
+
+## Methods
+
+Available on `services.symbolRegistry` inside a plugin.
+
+---
+
+### `setDefaults(defaults)`
+
+Set constructor-level defaults. Called automatically during app initialisation with the `symbolDefaults` constructor config. Plugin authors do not normally need to call this.
+
+---
+
+### `getDefaults()`
+
+Returns the merged app-wide defaults (hardcoded `symbolDefaults.js` + constructor overrides).
+
+```js
+const defaults = services.symbolRegistry.getDefaults()
+// { symbol: 'pin', backgroundColor: '#ca3535', selectedColor: { outdoor: '#0b0c0c', dark: '#ffffff' }, ... }
+```
+
+---
+
+### `register(symbolDef)`
+
+Register a custom symbol. Once registered it can be referenced by ID via `MarkerOptions.symbol` or a dataset `style.symbol`.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | Yes | Unique symbol identifier |
+| `svg` | `string` | Yes | Inner SVG path content with `{{token}}` placeholders — see [SVG structure](./symbol-config.md#svg-structure) |
+| `viewBox` | `string` | Yes | SVG viewBox, e.g. `'0 0 38 38'` |
+| `anchor` | `[number, number]` | Yes | Normalised [x, y] anchor point |
+| *(token)* | `string \| Record<string, string>` | No | Default token value for this symbol, e.g. `backgroundColor: '#1d70b8'`. `selectedColor` and `selectedWidth` are ignored here — set them via constructor `symbolDefaults`. |
+
+```js
+services.symbolRegistry.register({
+  id: 'star',
+  viewBox: '0 0 38 38',
+  anchor: [0.5, 0.5],
+  backgroundColor: '#1d70b8',
+  svg: `
+    <path d="..." fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
+    <path d="..." fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
+    <path d="..." fill="{{foregroundColor}}"/>
+  `
+})
+```
+
+See [Symbol Config](./symbol-config.md) for the full list of token properties and the SVG structure convention.
+
+---
+
+### `get(id)`
+
+Returns the symbol definition for the given ID, or `undefined` if not registered.
+
+```js
+const symbolDef = services.symbolRegistry.get('pin')
+```
+
+---
+
+### `list()`
+
+Returns an array of all registered symbol definitions.
+
+```js
+const symbols = services.symbolRegistry.list()
+```
+
+---
+
+### `resolve(symbolDef, styleColors, mapStyleId)`
+
+Resolves a symbol's SVG for **normal (unselected) rendering**. The `{{selectedColor}}` token is always replaced with an empty string — the selection ring is structurally present but invisible.
+
+```js
+const svg = services.symbolRegistry.resolve(
+  services.symbolRegistry.get('pin'),
+  { backgroundColor: '#d4351c' },
+  'outdoor'
+)
+```
+
+---
+
+### `resolveSelected(symbolDef, styleColors, mapStyleId)`
+
+Resolves a symbol's SVG for **selected rendering**. The `{{selectedColor}}` token uses the cascade value. Use this when rendering the highlight layer for an interact or datasets selection.
+
+```js
+const svg = services.symbolRegistry.resolveSelected(
+  services.symbolRegistry.get('pin'),
+  { backgroundColor: '#d4351c' },
+  'outdoor'
+)
+```

package/docs/api.md

@@ -161,7 +161,7 @@ The button is only displayed when the map is `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`.
@@ -264,18 +264,6 @@ URL query parameter key used to persist map visibility state.
 
 ---
 
-### `markerColor`
-**Type:** `string | Object<string, string>`
-**Default:** `'#ff0000'`
-
-Default colour for map markers. Can be overridden per marker when calling `addMarker()`.
-
-May be provided as:
-- A single colour value applied to all map styles
-- An object keyed by map style ID, allowing different colours per style
-
----
-
 ### `markers`
 **Type:** `MarkerConfig[]`
 
@@ -285,14 +273,29 @@ See [MarkerConfig](./api/marker-config.md) for full details.
 
 ---
 
-### `markerShape`
-**Type:** `string`
-**Default:** `'pin'`
+### `symbolDefaults`
+**Type:** `Partial<SymbolDefaults>`
 
-Default shape for map markers. Can be overridden per marker when calling `addMarker()`.
+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:
 
-> [!NOTE]
-> Currently only `'pin'` is available. Additional shapes are planned for a future release.
+| Property | Built-in default |
+|---|---|
+| `symbol` | `'pin'` |
+| `backgroundColor` | `'#ca3535'` |
+| `foregroundColor` | `'#ffffff'` |
+| `haloWidth` | `'1'` |
+| `selectedWidth` | `'6'` |
+
+```js
+new InteractiveMap('map', {
+  symbolDefaults: {
+    symbol: 'circle',
+    backgroundColor: { outdoor: '#1d70b8', dark: '#4c9ed9' }
+  }
+})
+```
+
+See [Symbol Config](./api/symbol-config.md) for the full property list.
 
 ---
 
@@ -488,7 +491,7 @@ Add a marker to the map.
 | `options` | [`MarkerOptions`](./api/marker-config.md#markeroptions) | Optional marker appearance options |
 
 ```js
-interactiveMap.addMarker('home', [-0.1276, 51.5074], { color: '#0000ff' })
+interactiveMap.addMarker('home', [-0.1276, 51.5074], { backgroundColor: '#1d70b8' })
 ```
 
 ---
@@ -547,7 +550,7 @@ interactiveMap.addButton('my-menu', {
 
 ### `addPanel(id, config)`
 
-Add a panel to the UI at runtime.
+Add a panel 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 |
 |-----------|------|-------------|
@@ -582,16 +585,20 @@ interactiveMap.removePanel('info-panel')
 
 ---
 
-### `showPanel(id)`
+### `showPanel(id, options?)`
 
-Show a panel.
+Show a panel. Focus is moved to the panel by default — set `focus: false` to suppress this, useful when showing a panel and you want focus to remain on the 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 })
 ```
 
 ---
@@ -711,6 +718,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/examples/add-marker-with-panel.mdx

@@ -0,0 +1,59 @@
+import DemoMapMarkerPanel from '../../demo/DemoMapMarkerPanel.js'
+
+# Add a marker with a panel
+
+Add markers to the map and allow users to select them. Selecting a marker fires the `interact:selectionchange` event, which can be used to show a panel with relevant information.
+
+<DemoMapMarkerPanel />
+
+```js
+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({
+  deselectOnClickOutside: true
+})
+
+const map = new InteractiveMap('my-map', {
+  behaviour: 'inline',
+  mapProvider: maplibreProvider(),
+  mapStyle: {
+    url: 'https://your-tile-url/style.json',
+    attribution: 'Your tile attribution'
+  },
+  center: [-2.96, 54.43],
+  zoom: 15,
+  containerHeight: '500px',
+  plugins: [interactPlugin]
+})
+
+map.on('map:ready', () => {
+  map.addMarker('my-marker', [-2.96, 54.43])
+  interactPlugin.enable()
+  interactPlugin.selectMarker('my-marker')
+
+  map.addPanel('marker-info', {
+    focus: false,
+    label: 'Marker',
+    html: '<p class="govuk-body">Information about the selected marker</p>',
+    mobile: { slot: 'drawer', dismissible: true },
+    tablet: { slot: 'left-top', dismissible: true, width: '280px' },
+    desktop: { slot: 'left-top', dismissible: true, width: '280px' }
+  })
+})
+
+map.on('interact:selectionchange', ({ selectedMarkers }) => {
+  if (selectedMarkers.length > 0) {
+    map.showPanel('marker-info')
+  } else {
+    map.hidePanel('marker-info')
+  }
+})
+
+map.on('app:panelclosed', ({ panelId }) => {
+  if (panelId === 'marker-info') {
+    interactPlugin.unselectMarker('my-marker')
+  }
+})
+```

package/docs/examples/basic-map.mdx

@@ -0,0 +1,24 @@
+import DemoMapBasic from '../../demo/DemoMapBasic.js'
+
+# Basic map
+
+Embed an interactive map directly on the page, allowing users to explore and interact with the map without leaving the current context.
+
+<DemoMapBasic />
+
+```js
+import InteractiveMap from '@defra/interactive-map'
+import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+
+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: '500px'
+})
+```

package/docs/examples/button-map.mdx

@@ -0,0 +1,24 @@
+import DemoMapButton from '../../demo/DemoMapButton.js'
+
+# Button-triggered map
+
+Trigger the map to show on button press, allowing users to access the map when needed without it taking up space on the page by default.
+
+<DemoMapButton />
+
+```js
+import InteractiveMap from '@defra/interactive-map'
+import maplibreProvider from '@defra/interactive-map/providers/maplibre'
+
+new InteractiveMap('my-map', {
+  behaviour: 'buttonFirst',
+  mapProvider: maplibreProvider(),
+  mapStyle: {
+    url: 'https://your-tile-url/style.json',
+    attribution: 'Your tile attribution'
+  },
+  center: [-1.6, 53.1],
+  zoom: 6,
+  hasExitButton: true
+})
+```

package/docs/examples/index.mdx

@@ -0,0 +1,49 @@
+import useBaseUrl from '@docusaurus/useBaseUrl'
+import basicMapImg from '../assets/basic-map.jpg'
+import buttonFirstImg from '../assets/button-first.jpg'
+import makerPanelImg from '../assets/maker-panel.jpg'
+
+export function ExampleCards() {
+  const basicHref = useBaseUrl('/examples/basic-map')
+  const buttonHref = useBaseUrl('/examples/button-map')
+  const interactHref = useBaseUrl('/examples/add-marker-with-panel')
+
+  return (
+    <div className='govuk-grid-row'>
+      <div className='govuk-grid-column-one-half'>
+        <div className='app-example-card'>
+          <img src={basicMapImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-m'>
+              <a href={basicHref}>Basic map</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-half'>
+        <div className='app-example-card'>
+          <img src={buttonFirstImg} alt='' />
+          <div className='app-example-card__body'>
+            <h2 className='govuk-heading-m'>
+              <a href={buttonHref}>Button-triggered map</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+      <div className='govuk-grid-column-one-half'>
+        <div className='app-example-card'>
+          <img src={makerPanelImg} alt='' />
+          <div className='app-example-card__body' style={{ 'border-top': '1px solid #cecece'}}>
+            <h2 className='govuk-heading-m'>
+              <a href={interactHref}>Add a marker with a panel</a>
+            </h2>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+# Examples
+
+<ExampleCards />

package/docs/index.mdx

@@ -26,7 +26,7 @@ import Link from '@docusaurus/Link';
         <h3><Link to="/getting-started" className="govuk-link">Getting Started</Link></h3>
         <p>How to install and configure the component. Covers setup, initialisation options, and integration with common build tools.</p>
         <h3><Link to="/examples" className="govuk-link">Examples</Link></h3>
-        <p>Live interactive demos showing the component in action, including inline maps, button-triggered maps, and various configuration options.</p>
+        <p>Live interactive demos showing the component in action, including basic maps, button-triggered maps, and various configuration options.</p>
         <h3><Link to="/api" className="govuk-link">API Reference</Link></h3>
         <p>Full reference for all configuration options, events, methods, and plugin interfaces exposed by the component.</p>
         <h3><Link to="/plugins" className="govuk-link">Plugins</Link></h3>

package/docs/plugins/datasets.md

@@ -1,6 +1,6 @@
 # Datasets Plugin
 
-The datasets plugin renders GeoJSON and vector tile datasets on the map, with support for sublayer style rules, layer visibility toggling, a key panel, and runtime style and data updates.
+The datasets plugin renders GeoJSON and vector tile datasets on the map, with support for polygon, line, and symbol (point) layer types, sublayer style rules, layer visibility toggling, a key panel, and runtime style and data updates.
 
 ## Usage
 
@@ -263,6 +263,15 @@ Overrides the shape used to render the key symbol for this dataset. Defaults to
 
 Visual style for the dataset. All style properties must be nested within this object.
 
+**Common properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `opacity` | `number` | Layer opacity from `0` to `1` |
+| `symbolDescription` | `string \| Record<string, string>` | Accessible description of the symbol shown in the key |
+
+**Polygon/line properties:**
+
 | Property | Type | Description |
 |----------|------|-------------|
 | `stroke` | `string \| Record<string, string>` | Stroke (outline) colour. Accepts a plain colour string or a map-style-keyed object e.g. `{ outdoor: '#ff0000', dark: '#ffffff' }` |
@@ -273,17 +282,56 @@ Visual style for the dataset. All style properties must be nested within this ob
 | `fillPatternSvgContent` | `string` | Raw SVG content for a custom fill pattern |
 | `fillPatternForegroundColor` | `string \| Record<string, string>` | Foreground colour for the fill pattern |
 | `fillPatternBackgroundColor` | `string \| Record<string, string>` | Background colour for the fill pattern |
-| `opacity` | `number` | Layer opacity from `0` to `1` |
-| `symbolDescription` | `string \| Record<string, string>` | Accessible description of the symbol shown in the key |
 | `keySymbolShape` | `'polygon' \| 'line'` | Shape used for the key symbol |
 
+**Symbol (point) properties:**
+
+Setting `symbol` or `symbolSvgContent` renders the dataset as a point layer instead of a polygon/line layer.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `symbol` | `string` | Registered symbol ID e.g. `'pin'`, `'circle'`, `'square'` |
+| `symbolSvgContent` | `string` | Inline SVG content for a fully custom symbol (no `<svg>` wrapper). Takes precedence over `symbol` |
+| `symbolViewBox` | `string` | SVG viewBox for the symbol e.g. `'0 0 38 38'`. Defaults to the registered symbol's viewBox |
+| `symbolAnchor` | `[number, number]` | Anchor point as a normalised `[x, y]` pair. Defaults to the registered symbol's anchor |
+| `symbolBackgroundColor` | `string \| Record<string, string>` | Background fill colour of the symbol |
+| `symbolForegroundColor` | `string \| Record<string, string>` | Foreground fill colour of the symbol (e.g. the inner dot) |
+| `symbolHaloWidth` | `string` | Stroke width of the halo in SVG units |
+| `symbolGraphic` | `string` | SVG `d` attribute for the foreground graphic path. Use named values (`'dot'`, `'cross'`, `'diamond'`, `'triangle'`, `'square'`) or supply your own path data |
+
+Symbol colour properties use the `symbol` prefix to distinguish them from polygon/line properties in the same style object. They follow the same resolution order and support style-keyed colour objects in the same way as markers — see [Symbol Config](../api/symbol-config.md) for details.
+
+`haloColor` and `selectedColor` are not settable here — they are basemap-level properties set on [`MapStyleConfig`](../api/map-style-config.md).
+
 ```js
+// Polygon/line dataset
 style: {
   stroke: { outdoor: '#d4351c', dark: '#ffffff' },
   strokeWidth: 2,
   fill: 'rgba(212,53,28,0.1)',
   symbolDescription: { outdoor: 'Red outline' }
 }
+
+// Point dataset — registered symbol with colour overrides
+style: {
+  symbol: 'pin',
+  symbolBackgroundColor: '#1d70b8',
+  symbolForegroundColor: '#ffffff'
+}
+
+// Point dataset — style-keyed colours for multi-basemap support
+style: {
+  symbol: 'pin',
+  symbolBackgroundColor: { outdoor: '#1d70b8', dark: '#5694ca' }
+}
+
+// Point dataset — custom inline SVG
+style: {
+  symbolSvgContent: '<circle cx="19" cy="19" r="12" fill="{{backgroundColor}}"/>',
+  symbolViewBox: '0 0 38 38',
+  symbolAnchor: [0.5, 0.5],
+  symbolBackgroundColor: '#1d70b8'
+}
 ```
 
 ---
@@ -292,9 +340,9 @@ style: {
 
 **Type:** `Sublayer[]`
 
-Array of sublayer rules that partition the dataset into visually distinct groups based on feature filters. Each sublayer is rendered as a separate pair of map layers.
+Array of sublayer rules that partition the dataset into visually distinct groups based on feature filters. Each sublayer is rendered as a separate map layer.
 
-Sublayers inherit the parent dataset's style and only override what they specify. Fill precedence (highest to lowest): sublayer's own `fillPattern` → sublayer's own `fill` → parent's `fillPattern` → parent's `fill`.
+Sublayers inherit the parent dataset's style and only override what they specify in their own `style` object. For polygon/line datasets, fill precedence is (highest to lowest): sublayer `fillPattern` → sublayer `fill` → parent `fillPattern` → parent `fill`. For symbol datasets, each symbol property is inherited individually from the parent unless the sublayer sets it explicitly.
 
 #### `Sublayer` properties
 
@@ -303,10 +351,12 @@ Sublayers inherit the parent dataset's style and only override what they specify
 | `id` | `string` | **Required.** Unique identifier within the dataset |
 | `label` | `string` | Human-readable name shown in the Layers and Key panels |
 | `filter` | `FilterExpression` | MapLibre filter expression to match features for this sublayer |
-| `style` | `Object` | Style overrides for this sublayer. Accepts the same properties as the dataset `style` object |
+| `style` | `Object` | Style overrides. Accepts the same properties as the dataset `style` object |
 | `showInKey` | `boolean` | Shows this sublayer in the Key panel. Inherits from dataset if not set |
 | `toggleVisibility` | `boolean` | Shows this sublayer in the Layers panel. **Default:** `false` |
 
+**Polygon/line example:**
+
 ```js
 sublayers: [
   {
@@ -334,6 +384,44 @@ sublayers: [
 ]
 ```
 
+**Symbol (point) example — scheduled monuments by type:**
+
+When the parent dataset has `symbol` set, each sublayer can override individual symbol properties to represent different categories. Properties not set on the sublayer are inherited from the parent.
+
+```js
+{
+  id: 'scheduled-monuments',
+  geojson: scheduledMonumentsData,
+  style: { symbol: 'square' },
+  sublayers: [
+    {
+      id: 'prehistoric',
+      label: 'Prehistoric sites',
+      filter: ['==', ['get', 'type'], 'prehistoric'],
+      showInKey: true,
+      toggleVisibility: true,
+      style: { symbolBackgroundColor: '#0f7a52' }
+    },
+    {
+      id: 'roman',
+      label: 'Roman sites',
+      filter: ['==', ['get', 'type'], 'roman'],
+      showInKey: true,
+      toggleVisibility: true,
+      style: { symbolBackgroundColor: '#54319f' }
+    },
+    {
+      id: 'medieval',
+      label: 'Medieval sites',
+      filter: ['==', ['get', 'type'], 'medieval'],
+      showInKey: true,
+      toggleVisibility: true,
+      style: { symbolBackgroundColor: '#ca357c' }
+    }
+  ]
+}
+```
+
 ---
 
 ## Methods
@@ -436,24 +524,32 @@ datasetsPlugin.setFeatureVisibility(true, [123, 456], {
 
 Update the visual style of a dataset or sublayer at runtime. When targeting a sublayer, only the properties specified are overridden — the sublayer inherits all other styles from the parent dataset.
 
+For symbol datasets, pass `symbol` as the style property to change the symbol config.
+
 | Argument | Type | Description |
 |----------|------|-------------|
-| `style` | `Object` | Style properties to apply. Accepts the same properties as `dataset.style` |
+| `style` | `Object` | Style properties to apply. Accepts the same properties as `dataset.style`, plus `symbol` |
 | `scope.datasetId` | `string` | ID of the dataset |
 | `scope.sublayerId` | `string` | Optional. When provided, targets a single sublayer |
 
 ```js
-// Dataset level
+// Polygon/line dataset
 datasetsPlugin.setStyle(
   { stroke: '#0000ff', strokeWidth: 3 },
   { datasetId: 'my-parcels' }
 )
 
-// Sublayer level
+// Sublayer — polygon
 datasetsPlugin.setStyle(
   { stroke: '#00703c', fillPattern: 'diagonal-cross-hatch', fillPatternForegroundColor: '#00703c' },
   { datasetId: 'my-parcels', sublayerId: 'active' }
 )
+
+// Sublayer — symbol colour override
+datasetsPlugin.setStyle(
+  { symbolBackgroundColor: '#912b88' },
+  { datasetId: 'flood-warnings', sublayerId: 'severe' }
+)
 ```
 
 ---