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

package/src/services/symbolRegistry.js

@@ -0,0 +1,113 @@
+import { getValueForStyle } from '../utils/getValueForStyle.js'
+import { symbolDefaults, pin, circle, square, graphics } from '../config/symbolConfig.js'
+import { SCHEME_COLORS } from '../config/mapTheme.js'
+
+const symbols = new Map()
+let _constructorDefaults = {}
+
+// Keys that are structural — not token values for SVG substitution
+const STRUCTURAL = new Set(['id', 'svg', 'viewBox', 'anchor', 'symbol', 'symbolSvgContent'])
+
+// selectedWidth is app-wide — not overridable at symbol registration level.
+// selectedColor is a map style concern — always injected from mapStyle, never from cascade.
+const REGISTRY_EXCLUDED = new Set([...STRUCTURAL, 'selectedWidth'])
+
+function resolveValues (symbolDef, markerValues, mapStyle) {
+  const mapStyleId = mapStyle?.id
+  const symbolTokens = Object.fromEntries(
+    Object.entries(symbolDef || {}).filter(([k]) => !REGISTRY_EXCLUDED.has(k))
+  )
+  const constructorTokens = Object.fromEntries(
+    Object.entries(_constructorDefaults).filter(([k]) => !STRUCTURAL.has(k))
+  )
+  const defined = Object.fromEntries(
+    Object.entries(markerValues).filter(([, v]) => v != null)
+  )
+  const merged = { ...symbolDefaults, ...constructorTokens, ...symbolTokens, ...defined }
+  // haloColor and selectedColor are map style concerns — always injected from mapStyle, never from the cascade
+  const scheme = SCHEME_COLORS[mapStyle?.mapColorScheme] ?? SCHEME_COLORS.light
+  merged.haloColor = mapStyle?.haloColor ?? scheme.haloColor
+  merged.selectedColor = mapStyle?.selectedColor ?? scheme.selectedColor
+  if (typeof merged.graphic === 'string' && graphics[merged.graphic]) {
+    merged.graphic = graphics[merged.graphic]
+  }
+  return Object.fromEntries(
+    Object.entries(merged).map(([token, value]) => [token, getValueForStyle(value, mapStyleId) || ''])
+  )
+}
+
+function resolveLayer (svgString, values) {
+  return Object.entries(values).reduce(
+    (svg, [token, value]) => svg.replaceAll(`{{${token}}}`, value),
+    svgString
+  )
+}
+
+export const symbolRegistry = {
+  /**
+   * Set constructor-level defaults. Called once during app initialisation.
+   * Merges onto symbolDefaults to form the app-wide token baseline.
+   *
+   * @param {Object} defaults - Constructor symbolDefaults config
+   */
+  setDefaults (defaults) {
+    _constructorDefaults = defaults || {}
+  },
+
+  /**
+   * Returns the merged app-wide defaults (hardcoded + constructor overrides).
+   * Includes both structural properties (symbol, viewBox, anchor) and token values.
+   *
+   * @returns {Object}
+   */
+  getDefaults () {
+    return { ...symbolDefaults, ..._constructorDefaults }
+  },
+
+  register (symbolDef) {
+    symbols.set(symbolDef.id, symbolDef)
+  },
+
+  get (id) {
+    return symbols.get(id)
+  },
+
+  list () {
+    return [...symbols.values()]
+  },
+
+  /**
+   * Resolve a symbol's SVG string for normal (unselected) rendering.
+   * The selected ring is always hidden regardless of cascade values.
+   *
+   * @param {Object} symbolDef - Symbol definition
+   * @param {Object} styleColors - Token overrides
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, haloColor)
+   * @returns {string} Resolved SVG string
+   */
+  resolve (symbolDef, styleColors, mapStyle) {
+    const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
+    if (!symbolDef) { return '' }
+    colors.selectedColor = ''
+    return resolveLayer(symbolDef.svg, colors)
+  },
+
+  /**
+   * Resolve a symbol's SVG string for selected rendering.
+   * selectedColor comes from mapStyle.selectedColor (or the hardcoded fallback).
+   *
+   * @param {Object} symbolDef - Symbol definition
+   * @param {Object} styleColors - Token overrides
+   * @param {Object} mapStyle - Current map style config (provides selectedColor, haloColor)
+   * @returns {string} Resolved SVG string
+   */
+  resolveSelected (symbolDef, styleColors, mapStyle) {
+    const colors = resolveValues(symbolDef, styleColors || {}, mapStyle)
+    if (!symbolDef) { return '' }
+    return resolveLayer(symbolDef.svg, colors)
+  }
+}
+
+symbolRegistry.register(pin)
+symbolRegistry.register(circle)
+symbolRegistry.register(square)

package/src/services/symbolRegistry.test.js

@@ -0,0 +1,262 @@
+import { symbolRegistry } from './symbolRegistry.js'
+import { symbolDefaults } from '../config/symbolConfig.js'
+import { SCHEME_COLORS } from '../config/mapTheme.js'
+import { getValueForStyle } from '../utils/getValueForStyle.js'
+
+const STYLE_ID = 'test'
+const mapStyle = { id: STYLE_ID }
+
+beforeEach(() => {
+  symbolRegistry.setDefaults({})
+})
+
+describe('symbolRegistry — built-in symbols', () => {
+  it('registers pin by default', () => {
+    const pin = symbolRegistry.get('pin')
+    expect(pin).toBeDefined()
+    expect(pin.id).toBe('pin')
+    expect(pin.anchor).toEqual([0.5, 0.9])
+    expect(typeof pin.svg).toBe('string')
+  })
+
+  it('registers circle by default', () => {
+    const circle = symbolRegistry.get('circle')
+    expect(circle).toBeDefined()
+    expect(circle.id).toBe('circle')
+    expect(circle.anchor).toEqual([0.5, 0.5])
+  })
+
+  it('lists both built-in symbols', () => {
+    const ids = symbolRegistry.list().map(s => s.id)
+    expect(ids).toContain('pin')
+    expect(ids).toContain('circle')
+  })
+})
+
+describe('symbolRegistry — register / get', () => {
+  it('registers and retrieves a custom symbol', () => {
+    const custom = {
+      id: 'test-diamond',
+      viewBox: '0 0 20 20',
+      anchor: [0.5, 0.5],
+      svg: '<rect fill="{{backgroundColor}}"/>'
+    }
+    symbolRegistry.register(custom)
+    expect(symbolRegistry.get('test-diamond')).toBe(custom)
+  })
+
+  it('returns undefined for an unregistered id', () => {
+    expect(symbolRegistry.get('does-not-exist')).toBeUndefined()
+  })
+})
+
+describe('symbolRegistry — setDefaults / getDefaults', () => {
+  it('getDefaults returns hardcoded defaults when no constructor defaults set', () => {
+    const defaults = symbolRegistry.getDefaults()
+    expect(defaults.symbol).toBe('pin')
+    expect(defaults.backgroundColor).toBe(symbolDefaults.backgroundColor)
+  })
+
+  it('constructor defaults override hardcoded defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#ff0000', symbol: 'circle' })
+    const defaults = symbolRegistry.getDefaults()
+    expect(defaults.backgroundColor).toBe('#ff0000')
+    expect(defaults.symbol).toBe('circle')
+  })
+
+  it('constructor defaults do not affect unset properties', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    const defaults = symbolRegistry.getDefaults()
+    expect(defaults.foregroundColor).toBe(symbolDefaults.foregroundColor)
+  })
+
+  it('setDefaults with null or undefined resets to hardcoded defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    symbolRegistry.setDefaults(null)
+    expect(symbolRegistry.getDefaults().backgroundColor).toBe(symbolDefaults.backgroundColor)
+  })
+})
+
+describe('symbolRegistry — resolve', () => {
+  const BACKGROUND_SVG = '<path fill="{{backgroundColor}}"/>'
+  const symbolDef = {
+    id: 'test',
+    svg: '<path fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/><path fill="{{foregroundColor}}" stroke="{{selectedColor}}"/>'
+  }
+
+  it('injects default token values when no overrides given', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.foregroundColor, STYLE_ID)}"`)
+    expect(resolved).toContain(`stroke-width="${symbolDefaults.haloWidth}"`)
+  })
+
+  it('always produces empty selectedColor token — ring is hidden', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain('stroke=""')
+  })
+
+  it('uses light scheme haloColor when mapStyle has no haloColor', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.haloColor}"`)
+  })
+
+  it('uses mapStyle.haloColor when provided', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, {}, { id: STYLE_ID, haloColor: '#336699' })
+    expect(resolved).toContain('stroke="#336699"')
+  })
+
+  it('overrides default backgroundColor with a plain string', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: '#ff0000' }, mapStyle)
+    expect(resolved).toContain('fill="#ff0000"')
+  })
+
+  it('overrides default with a style-keyed color', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: { [STYLE_ID]: '#aabbcc', other: '#112233' } }, mapStyle)
+    expect(resolved).toContain('fill="#aabbcc"')
+  })
+
+  it('ignores null override values — defaults are preserved', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: null }, mapStyle)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
+  })
+
+  it('replaces custom tokens not in defaults', () => {
+    const customDef = { id: 'custom', svg: '<path fill="{{accentColor}}"/>' }
+    const resolved = symbolRegistry.resolve(customDef, { accentColor: '#123456' }, mapStyle)
+    expect(resolved).toContain('fill="#123456"')
+  })
+
+  it('handles null styleColors — uses all defaults', () => {
+    const resolved = symbolRegistry.resolve(symbolDef, null, mapStyle)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
+    expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.foregroundColor, STYLE_ID)}"`)
+  })
+
+  it('replaces token with empty string when override is an empty string', () => {
+    const def = { id: 'es', svg: BACKGROUND_SVG }
+    const resolved = symbolRegistry.resolve(def, { backgroundColor: '' }, mapStyle)
+    expect(resolved).toContain('fill=""')
+  })
+
+  it('returns empty string for null symbolDef', () => {
+    expect(symbolRegistry.resolve(null, {}, mapStyle)).toBe('')
+  })
+
+  it('constructor defaults take precedence over hardcoded defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#abcdef' })
+    const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
+    expect(resolved).toContain('fill="#abcdef"')
+  })
+
+  it('symbol-level token defaults take precedence over constructor defaults', () => {
+    symbolRegistry.setDefaults({ backgroundColor: '#abcdef' })
+    const defWithToken = { id: 'td', svg: BACKGROUND_SVG, backgroundColor: '#111111' }
+    const resolved = symbolRegistry.resolve(defWithToken, {}, mapStyle)
+    expect(resolved).toContain('fill="#111111"')
+  })
+
+  it('marker-level overrides take precedence over symbol-level defaults', () => {
+    const defWithToken = { id: 'td2', svg: BACKGROUND_SVG, backgroundColor: '#111111' }
+    const resolved = symbolRegistry.resolve(defWithToken, { backgroundColor: '#ffffff' }, mapStyle)
+    expect(resolved).toContain('fill="#ffffff"')
+  })
+})
+
+describe('symbolRegistry — resolveSelected', () => {
+  const symbolDef = {
+    id: 'test-sel',
+    svg: '<path stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/><path fill="{{backgroundColor}}"/>'
+  }
+
+  it('uses light scheme selectedColor when mapStyle has no selectedColor', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+  })
+
+  it('uses mapStyle.selectedColor when provided', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
+    expect(resolved).toContain('stroke="#ff0000"')
+  })
+
+  it('uses selectedWidth from symbolDefaults', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke-width="${symbolDefaults.selectedWidth}"`)
+  })
+
+  it('handles null styleColors — uses cascade defaults', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, null, mapStyle)
+    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+  })
+
+  it('returns empty string for null symbolDef', () => {
+    expect(symbolRegistry.resolveSelected(null, {}, mapStyle)).toBe('')
+  })
+
+  it('symbol-level selectedColor is ignored — mapStyle wins', () => {
+    const defWithSelected = { ...symbolDef, selectedColor: '#00ff00' }
+    const resolved = symbolRegistry.resolveSelected(defWithSelected, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
+    expect(resolved).toContain('stroke="#ff0000"')
+  })
+
+  it('still resolves other tokens correctly', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, { backgroundColor: '#d4351c' }, mapStyle)
+    expect(resolved).toContain('fill="#d4351c"')
+  })
+})
+
+describe('symbolRegistry — graphic token', () => {
+  const graphicDef = {
+    id: 'test-graphic',
+    graphic: 'M10 10 L20 20',
+    svg: '<path d="{{graphic}}" fill="{{foregroundColor}}"/>'
+  }
+
+  it('substitutes graphic d attribute from symbol-level default', () => {
+    const resolved = symbolRegistry.resolve(graphicDef, {}, mapStyle)
+    expect(resolved).toContain('d="M10 10 L20 20"')
+  })
+
+  it('resolves named graphic string to built-in path data', () => {
+    const resolved = symbolRegistry.resolve(graphicDef, { graphic: 'cross' }, mapStyle)
+    expect(resolved).toContain('d="M6 3H10V6H13V10H10V13H6V10H3V6H6Z"')
+  })
+
+  it('overrides symbol-level graphic with marker-level value', () => {
+    const resolved = symbolRegistry.resolve(graphicDef, { graphic: 'M0 0 L38 38' }, mapStyle)
+    expect(resolved).toContain('d="M0 0 L38 38"')
+  })
+
+  it('overrides graphic via constructor defaults', () => {
+    symbolRegistry.setDefaults({ graphic: 'M5 5 L15 15' })
+    const defNoGraphic = { id: 'no-graphic', svg: '<path d="{{graphic}}"/>' }
+    const resolved = symbolRegistry.resolve(defNoGraphic, {}, mapStyle)
+    expect(resolved).toContain('d="M5 5 L15 15"')
+  })
+
+  it('marker-level graphic overrides constructor default', () => {
+    symbolRegistry.setDefaults({ graphic: 'M5 5 L15 15' })
+    const defNoGraphic = { id: 'no-graphic2', svg: '<path d="{{graphic}}"/>' }
+    const resolved = symbolRegistry.resolve(defNoGraphic, { graphic: 'M1 1 L2 2' }, mapStyle)
+    expect(resolved).toContain('d="M1 1 L2 2"')
+  })
+
+  it('built-in pin symbol has a graphic default', () => {
+    const pin = symbolRegistry.get('pin')
+    expect(typeof pin.graphic).toBe('string')
+    expect(pin.graphic.length).toBeGreaterThan(0)
+  })
+
+  it('built-in circle symbol has a graphic default', () => {
+    const circle = symbolRegistry.get('circle')
+    expect(typeof circle.graphic).toBe('string')
+    expect(circle.graphic.length).toBeGreaterThan(0)
+  })
+
+  it('pin resolves graphic token into its svg within a g transform', () => {
+    const pin = symbolRegistry.get('pin')
+    const resolved = symbolRegistry.resolve(pin, {}, mapStyle)
+    expect(resolved).toContain(`d="${pin.graphic}"`)
+    expect(resolved).toContain('translate(19, 16) scale(0.8) translate(-8, -8)')
+  })
+})

package/src/types.js

@@ -316,15 +316,67 @@
  * Alt text for logo.
  *
  * @property {'light' | 'dark'} [mapColorScheme]
- * Map color scheme. Used to determine the style of controls on the map. eg. Halo colours etc
+ * Map colour scheme. Sets the default values of `haloColor`, `selectedColor`, and `foregroundColor`
+ * when not explicitly provided, and signals to map overlay components which tonal range to use.
+ * `'light'` (default): dark overlays on a light basemap. `'dark'`: light overlays on a dark or aerial basemap.
  *
  * @property {string} [thumbnail]
  * URL to thumbnail image.
  *
+ * @property {string} [haloColor]
+ * Halo colour for elements rendered on top of the map (e.g. symbol outlines). Provides contrast
+ * between overlay elements and the map background. Falls back to `#ffffff` (light) or `#0b0c0c` (dark).
+ * Injected as the `--map-overlay-halo-color` CSS custom property.
+ *
+ * @property {string} [selectedColor]
+ * Theme colour for selected state — used by map overlay components to indicate a selected feature.
+ * Falls back to `#0b0c0c` (light) or `#ffffff` (dark).
+ * Injected as the `--map-overlay-selected-color` CSS custom property.
+ *
+ * @property {string} [foregroundColor]
+ * Foreground colour for elements rendered on top of the map (e.g. text or iconography in overlay components).
+ * Falls back to `#0b0c0c` (light) or `#ffffff` (dark).
+ * Injected as the `--map-overlay-foreground-color` CSS custom property.
+ *
  * @property {string} url
  * URL to the style.json (Mapbox Style Specification).
  */
 
+/**
+ * App-wide symbol appearance defaults. All properties are optional.
+ * Color values may be a plain string or an object keyed by map style ID.
+ *
+ * @typedef {Object} SymbolDefaults
+ *
+ * @property {string} [symbol='pin']
+ * Default symbol ID. Built-in values: `'pin'`, `'circle'`.
+ *
+ * @property {string} [symbolSvgContent]
+ * Default inner SVG path content. When set, overrides `symbol`.
+ *
+ * @property {string} [viewBox='0 0 38 38']
+ * Default SVG viewBox.
+ *
+ * @property {[number, number]} [anchor=[0.5, 0.5]]
+ * Default anchor point as a normalised [x, y] pair.
+ *
+ * @property {string | Record<string, string>} [backgroundColor='#ca3535']
+ * Default background fill colour.
+ *
+ * @property {string | Record<string, string>} [foregroundColor='#ffffff']
+ * Default foreground fill colour.
+ *
+ * @property {string} [haloWidth='1']
+ * Default halo stroke width in SVG units.
+ *
+ * @property {string} [graphic]
+ * Default SVG `d` attribute value for the foreground graphic path. Each built-in symbol sets
+ * its own default (a small dot). Override to swap the graphic across all markers globally.
+ *
+ * @property {string} [selectedWidth='6']
+ * Selection ring stroke width in SVG units. App-wide only — ignored at symbol registration and marker creation level.
+ */
+
 /**
  * Configuration for a map marker.
  *
@@ -341,15 +393,47 @@
  */
 
 /**
- * Options for customizing marker appearance.
+ * Options for customizing marker appearance. Any key corresponds to a token in the symbol's SVG template.
+ * Color values may be a plain string or an object keyed by map style ID e.g. `{ outdoor: '#fff', dark: '#000' }`.
  *
  * @typedef {Object} MarkerOptions
  *
- * @property {string | Record<string, string>} [color]
- * Marker color or object with colors keyed by style ID.
+ * @property {string} [symbol]
+ * Symbol id to use for this marker (e.g. 'pin', 'circle'). Overrides the default `symbolDefaults.symbol` option.
+ *
+ * @property {string} [symbolSvgContent]
+ * Inner SVG path content (no `<svg>` wrapper) to use instead of a registered symbol.
+ * Use `{{token}}` placeholders for colours — e.g. `fill="{{backgroundColor}}"`.
+ * When set, `symbol` is ignored.
+ *
+ * @property {string} [viewBox]
+ * SVG viewBox attribute for the symbol, e.g. `'0 0 38 38'`.
+ * Defaults to the registered symbol's viewBox, or `'0 0 38 38'`.
+ *
+ * @property {[number, number]} [anchor]
+ * Anchor point as a normalised [x, y] pair where [0, 0] is top-left and [1, 1] is bottom-right.
+ * Determines which point on the symbol aligns with the geographic coordinate.
+ * Defaults to the registered symbol's anchor, or `[0.5, 0.5]` (centre).
+ *
+ * @property {string | Record<string, string>} [backgroundColor]
+ * Background fill colour of the symbol.
+ *
+ * @property {string | Record<string, string>} [foregroundColor]
+ * Foreground fill colour of the symbol (e.g. the inner dot on a pin).
+ *
+ * @property {string} [haloWidth]
+ * Stroke width of the halo in SVG units. Defaults to `'1'`.
+ *
+ * @property {string} [graphic]
+ * SVG `d` attribute value for the foreground graphic path. Replaces the foreground shape of the
+ * symbol while keeping its background, halo and selection ring intact. Each built-in symbol
+ * (`pin`, `circle`) provides a default dot; pass a different `d` string to swap it.
+ * Use named values from `graphics.js` or supply your own path data.
+ *
+ * @example
+ * import { graphics } from './config/symbolConfig.js'
+ * markers.add('id', coords, { symbol: 'pin', graphic: graphics.cross })
  *
- * @property {string} [shape]
- * Marker shape (e.g., 'pin').
  */
 
 /**
@@ -507,7 +591,7 @@
  * @property {boolean} [enableFullscreen=false]
  * Whether a toggle fullscreen button is displayed.
  *
- * @property {boolean} [enableZoomControls=false]
+ * @property {boolean} [enableZoomControls=true]
  * Whether zoom control buttons are displayed.
  *
  * @property {[number, number, number, number]} [extent]
@@ -540,14 +624,12 @@
  * @property {string} [mapViewParamKey='mv']
  * URL query parameter key used to control map view state.
  *
- * @property {string | Record<string, string>} [markerColor='#ff0000']
- * Colour used for map markers. May be a single colour value or an object keyed by map style ID.
- *
  * @property {MarkerConfig[]} [markers]
  * Initial markers to display on the map.
  *
- * @property {string} [markerShape='pin']
- * Shape used for map markers.
+ * @property {Partial<SymbolDefaults>} [symbolDefaults]
+ * App-wide defaults for symbol appearance. Merged onto the hardcoded defaults in symbolDefaults.js.
+ * Values cascade: symbolDefaults.js → constructor symbolDefaults → symbol registration → marker creation.
  *
  * @property {[number, number, number, number]} [maxExtent]
  * Maximum viewable extent [west, south, east, north].
@@ -579,6 +661,11 @@
  * @property {PluginDescriptor[]} [plugins]
  * Plugins to load.
  *
+ * @property {boolean} [manageHistoryState=true]
+ * Whether the library should manage browser history state (pushState/replaceState) when opening and closing the map.
+ * Set to `false` in SPA frameworks (e.g. React Router, Docusaurus) that intercept history API calls.
+ * When `false`, listen to `APP_OPENED` and `APP_CLOSED` events and manage navigation in your router instead.
+ *
  * @property {boolean} [preserveStateOnClose=false]
  * Whether to preserve the map state when closed via back button or exit button.
  * When true, the map is hidden but not destroyed, preserving markers, zoom, etc.

package/src/utils/mapStateSync.js

@@ -1,4 +1,11 @@
-// Internal (not exported) - Accept optional search string for testing
+/**
+ * Reads center and zoom for a given map ID from a URL search string.
+ * The `search` parameter is accepted explicitly to keep this function pure and testable.
+ *
+ * @param {string} id - Map instance ID.
+ * @param {string} search - URL search string (e.g. `window.location.search`).
+ * @returns {{ center: [number, number], zoom: number } | null}
+ */
 const getMapStateFromURL = (id, search) => {
   const params = new URLSearchParams(search)
   const centerStr = params.get(`${id}:center`)
@@ -11,30 +18,61 @@ const getMapStateFromURL = (id, search) => {
   return { center: [lng, lat], zoom }
 }
 
+/**
+ * Persists map center and zoom into the page URL without triggering navigation.
+ *
+ * Existing query parameters are preserved. Parameters for this map ID are
+ * replaced if already present. Builds the URL manually to avoid percent-encoding
+ * colons and commas that URLSearchParams would otherwise encode.
+ *
+ * @param {string} id - Map instance ID, used as a namespace prefix for the params.
+ * @param {{ center?: [number, number], zoom?: number }} state - Map state to write.
+ * @param {string} [currentHref] - URL to update. Defaults to `window.location.href`.
+ * @returns {void}
+ */
 const setMapStateInURL = (id, state, currentHref = window.location.href) => {
-  // Use the passed href or the global one
   const url = new URL(currentHref || 'http://localhost')
-  const params = [...new URLSearchParams(url.search)].map(([key, value]) => `${key}=${value}`)
+
+  const newKeys = new Set()
   const newParams = []
 
   if (state.center) {
-    newParams.push(`${id}:center=${state.center[0]},${state.center[1]}`)
+    const key = `${id}:center`
+    newKeys.add(key)
+    newParams.push(`${key}=${state.center[0]},${state.center[1]}`)
   }
   if (state.zoom != null) {
-    newParams.push(`${id}:zoom=${state.zoom}`)
+    const key = `${id}:zoom`
+    newKeys.add(key)
+    newParams.push(`${key}=${state.zoom}`)
   }
 
-  const filteredParams = params.filter(p => {
-    return !newParams.some(np => np.split('=')[0] === p.split('=')[0])
+  const existingParams = []
+  url.searchParams.forEach((value, key) => {
+    if (!newKeys.has(key)) {
+      existingParams.push(`${key}=${value}`)
+    }
   })
 
-  const hash = url.hash || ''
-  const newUrl = `${url.origin}${url.pathname}?${[...filteredParams, ...newParams].join('&')}${hash}`
+  const allParams = [...existingParams, ...newParams].join('&')
+  const search = allParams ? '?' + allParams : ''
+  const newUrl = `${url.origin}${url.pathname}${search}${url.hash}`
   window.history.replaceState(window.history.state, '', newUrl)
 }
 
+/**
+ * Returns the initial map view state, preferring any saved state from the URL.
+ *
+ * Resolution order:
+ * 1. Center/zoom encoded in the URL search string for this map ID.
+ * 2. A `bounds` value if provided (used to fit the view on load).
+ * 3. The configured `center` and `zoom` defaults.
+ *
+ * @param {{ id: string, center: [number, number], zoom: number, bounds?: any }} config - Map config.
+ * @param {string} [search] - URL search string. Defaults to `window.location.search`.
+ * @returns {{ center: [number, number], zoom: number } | { bounds: any }}
+ */
 const getInitialMapState = ({ id, center, zoom, bounds }, search = window.location.search) => {
-  // Pass search string down to the internal function
   const savedState = getMapStateFromURL(id, search)
   if (savedState) {
     return {

package/src/utils/mapStateSync.test.js

@@ -33,11 +33,10 @@ describe('mapStateSync utilities', () => {
   })
 
   describe('setMapStateInURL', () => {
-    it('preserves history state and filters params (Line 28)', () => {
+    it('writes center and zoom into the URL', () => {
       const mockHref = 'http://test.com/path?existing=true'
       setMapStateInURL('map1', { center: [10, 20], zoom: 5 }, mockHref)
 
-      // Verification of Line 28: First arg must be global history state
       expect(globalThis.history.replaceState).toHaveBeenCalledWith(
         globalThis.history.state,
         '',
@@ -45,21 +44,42 @@ describe('mapStateSync utilities', () => {
       )
     })
 
-    it('uses fallback localhost URL (Line 17)', () => {
+    it('replaces existing map params when already present in the URL', () => {
+      setMapStateInURL('map1', { center: [10, 20], zoom: 5 }, 'http://test.com?map1:center=1,2&map1:zoom=3')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toContain('map1:center=10,20')
+      expect(url).toContain('map1:zoom=5')
+      expect(url).not.toContain('map1:center=1,2')
+    })
+
+    it('preserves unrelated existing params (e.g. mv)', () => {
+      setMapStateInURL('map1', { center: [10, 20], zoom: 5 }, 'http://test.com/path?mv=map1')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toContain('mv=map1')
+      expect(url).toContain('map1:center=10,20')
+    })
+
+    it('uses fallback localhost URL when href is null', () => {
       setMapStateInURL('map1', { zoom: 10 }, null)
-      const lastCall = globalThis.history.replaceState.mock.calls[0][2]
-      expect(lastCall).toContain('http://localhost')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toContain('http://localhost')
     })
 
-    it('handles state where zoom is nullish (Line 24)', () => {
+    it('omits zoom when zoom is null', () => {
       setMapStateInURL('map1', { center: [0, 0], zoom: null }, 'http://test.com')
-      const lastCall = globalThis.history.replaceState.mock.calls[0][2]
-      expect(lastCall).not.toContain('zoom')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).not.toContain('zoom')
     })
 
-    it('triggers the default href parameter', () => {
+    it('uses window.location.href when no href is provided', () => {
       setMapStateInURL('map1', { zoom: 10 })
       expect(globalThis.history.replaceState).toHaveBeenCalled()
     })
+
+    it('produces a URL with no search string when state is empty and no existing params', () => {
+      setMapStateInURL('map1', {}, 'http://test.com/path')
+      const url = globalThis.history.replaceState.mock.calls[0][2]
+      expect(url).toBe('http://test.com/path')
+    })
   })
 })