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

package/docs/api/symbol-config.md

@@ -0,0 +1,160 @@
+# Symbol Config
+
+Symbol properties control the appearance of markers and point dataset features. The same properties apply whether you are configuring a marker, app-wide defaults via the constructor `symbolDefaults`, or a custom symbol registration.
+
+## How values are resolved
+
+Each property is optional. A value set directly on a marker or dataset layer takes priority over everything else. If a property is not set there, the value registered with the symbol is used. If the symbol has no value for that property, the app-wide `symbolDefaults` from the constructor applies. If none of those are set, the built-in fallback listed under each property below is used.
+
+`haloColor`, `selectedColor`, `haloWidth`, and `selectedWidth` are required tokens in the SVG structure (see [SVG structure](#svg-structure)). Include them in any custom `symbolSvgContent` — the app resolves their values automatically. Note that `haloColor` and `selectedColor` are always derived from the active map style and cannot be configured.
+
+## Style-keyed colours
+
+Any colour property can be a plain string or an object keyed by map style ID. This lets a single config work across all basemaps:
+
+```js
+backgroundColor: '#d4351c'
+backgroundColor: { outdoor: '#d4351c', dark: '#ff6b6b' }
+```
+
+## Properties
+
+---
+
+### `symbol`
+**Type:** `string`
+**Default:** `'pin'`
+
+Registered symbol ID to use. Built-in values: `'pin'`, `'circle'`, `'square'`. Ignored when `symbolSvgContent` is set.
+
+---
+
+### `symbolSvgContent`
+**Type:** `string`
+
+Inner SVG path content (no `<svg>` wrapper) to render as the symbol. Use `{{token}}` placeholders for colours. When set, `symbol` is ignored.
+
+```js
+{
+  symbolSvgContent: `
+    <path d="..." fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
+    <path d="..." fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
+    <path d="..." fill="{{foregroundColor}}"/>
+  `,
+  viewBox: '0 0 38 38',
+  anchor: [0.5, 1]
+}
+```
+
+See [SVG structure](#svg-structure) for the standard three-layer pattern.
+
+---
+
+### `viewBox`
+**Type:** `string`
+**Default:** registered symbol's viewBox, or `'0 0 38 38'`
+
+SVG `viewBox` attribute. Use alongside `symbolSvgContent` when your paths use a different coordinate space.
+
+---
+
+### `anchor`
+**Type:** `[number, number]`
+**Default:** registered symbol's anchor, or `[0.5, 0.5]`
+
+Normalised `[x, y]` anchor point where `[0, 0]` is the top-left and `[1, 1]` is the bottom-right of the symbol. Determines which point on the symbol aligns with the geographic coordinate.
+
+```js
+anchor: [0.5, 1]   // bottom-centre — tip of a pin
+anchor: [0.5, 0.5] // centre — circle or dot
+```
+
+---
+
+### `backgroundColor`
+**Type:** `string | Record<string, string>`
+**Default:** `'#ca3535'`
+
+Background fill colour of the symbol shape.
+
+---
+
+### `foregroundColor`
+**Type:** `string | Record<string, string>`
+**Default:** `'#ffffff'`
+
+Foreground fill colour — the inner graphic element (e.g. the dot inside a pin).
+
+---
+
+### `haloWidth`
+**Type:** `number`
+**Default:** `1`
+
+Stroke width of the halo around the symbol background shape. Can be set in constructor `symbolDefaults`, at symbol registration, or per marker/dataset layer.
+
+---
+
+### `selectedWidth`
+**Type:** `number`
+**Default:** `6`
+
+Stroke width of the selection ring shown when a marker is selected. Can be set in constructor `symbolDefaults` or per marker/dataset layer.
+
+---
+
+### `graphic`
+**Type:** `string`
+
+SVG `d` attribute value for the foreground graphic path. Replaces the inner shape (e.g. the dot inside a pin) while keeping the background, halo and selection ring intact.
+
+Pass a built-in name or supply your own path data:
+
+```js
+// Named built-in — resolved automatically
+{ symbol: 'pin', graphic: 'cross' }
+
+// Inline path data
+{ symbol: 'pin', graphic: 'M14 12 L24 20 L14 28 Z' }
+```
+
+Built-in named graphics (16×16 coordinate space, centred at 8,8):
+
+| Name | Shape |
+|------|-------|
+| `'dot'` | Small filled circle — the default for `pin` and `circle` |
+| `'cross'` | Filled plus / cross |
+| `'diamond'` | Filled diamond / rotated square |
+| `'triangle'` | Filled upward-pointing triangle |
+| `'square'` | Filled square |
+
+`graphic` follows the full resolution order above — it can be set as a symbol default, a constructor default, or per item.
+
+---
+
+### Custom tokens
+
+Any `{{token}}` placeholder in a symbol SVG beyond the built-in set is substituted automatically if a matching key is present anywhere in the resolution order:
+
+```js
+// Symbol SVG contains: fill="{{accentColor}}"
+markers.add('id', coords, { accentColor: '#ffdd00' })
+```
+
+## SVG structure
+
+Symbols are defined as inner SVG path content (no `<svg>` wrapper) using `{{token}}` placeholders. The standard three-layer structure is:
+
+```js
+svg: `
+  <path d="..." fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
+  <path d="..." fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
+  <path d="..." fill="{{foregroundColor}}"/>
+`
+```
+
+- **Layer 1** — selection ring (stroke only, fill none) — hidden in normal rendering, visible when selected
+- **Layer 2** — background shape with halo stroke
+- **Layer 3** — foreground graphic (e.g. inner dot)
+
+> `{{haloColor}}` and `{{selectedColor}}` are always injected from the active map style. They must be present in the SVG but cannot be configured.

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

@@ -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' })
 ```
 
 ---
@@ -560,9 +563,9 @@ See [PanelDefinition](./api/panel-definition.md) for configuration options. When
 interactiveMap.addPanel('info-panel', {
   label: 'Information',
   html: '<p>Panel content here</p>',
-  mobile: { slot: 'bottom' },
-  tablet: { slot: 'left' },
-  desktop: { slot: 'left' }
+  mobile: { slot: 'drawer' },
+  tablet: { slot: 'left-top' },
+  desktop: { slot: 'left-top' }
 })
 ```
 

package/docs/getting-started.md

@@ -3,9 +3,12 @@
 ## Installation
 
 ```shell
-npm i @defra/interactive-map
+npm i @defra/interactive-map@x.y.z-alpha
 ```
 
+[!NOTE]  
+Install using a fixed version (e.g. npm install @defra/interactive-map@x.y.z-alpha) as this package is currently in alpha and may introduce breaking changes. Check the GitHub releases page for the latest available [version](https://github.com/DEFRA/interactive-map/tags).
+
 ### MapLibre provider (recommended)
 
 **ESM:** `maplibre-gl` is a peer dependency, install it separately: