@defra/interactive-map 0.0.21-alpha → 0.0.23-alpha

package/src/types.js

@@ -91,6 +91,41 @@
  * Core services (announce, reverseGeocode, closeApp, etc.).
  */
 
+/**
+ * Defines an item in a button's popup menu.
+ *
+ * @typedef {Object} MenuItemDefinition
+ *
+ * @property {string} id
+ * Unique item identifier. Used to control state via toggleButtonState().
+ *
+ * @property {string} label
+ * Display text for the item.
+ *
+ * @property {string} [iconId]
+ * Icon identifier from the icon registry.
+ *
+ * @property {string} [iconSvgContent]
+ * Raw SVG content for the item icon. The outer SVG tag should be excluded.
+ *
+ * @property {boolean} [isPressed]
+ * Initial checked state. When set, the item renders as menuitemcheckbox.
+ *
+ * @property {boolean} [keepFocus=false]
+ * When true, focus returns to the menu's trigger button after selection instead of
+ * moving to the panel (if panelId is set) or the map viewport.
+ *
+ * @property {(e: MouseEvent) => void} [onClick]
+ * Click handler. Receives the native event. Not called when panelId is set.
+ *
+ * @property {string} [panelId]
+ * Associated panel identifier. When set, selecting the item opens the panel and moves
+ * focus to it. onClick is not called.
+ *
+ * @property {(context: PluginContext) => boolean} [pressedWhen]
+ * Reactive callback to determine if the item should appear checked. Plugin buttons only.
+ */
+
 /**
  * Defines a button that can be rendered in the UI at various breakpoints.
  *
@@ -133,12 +168,21 @@
  * @property {string | (() => string)} label
  * Accesible label. Text or a function returning the text. Used for the label or tooltip if 'showLabel' is false.
  *
+ * @property {MenuItemDefinition[]} [menuItems]
+ * Items for the button's popup menu. When provided, the button acts as a menu trigger.
+ *
  * @property {ButtonBreakpointConfig} mobile
  * Mobile breakpoint configuration.
  *
  * @property {(event: MouseEvent, context: PluginContext) => void} [onClick]
  * Click handler for the button.
  *
+ * @property {boolean} [keepFocus=false]
+ * When true, focus remains on this button after activation instead of moving to the panel or viewport.
+ * Use for repeated incremental actions (e.g. zoom) where the user may activate the button
+ * multiple times. Toggle buttons (isPressed/pressedWhen) always keep focus regardless of this flag.
+ * When combined with panelId, the panel opens but focus stays on the button.
+ *
  * @property {string} [panelId]
  * Associated panel identifier to toggle open when clicked.
  *
@@ -221,6 +265,10 @@
  * @property {(point: { x: number, y: number }) => any[]} getFeaturesAtPoint
  * Query rendered features at a screen pixel position (x from left edge, y from top edge of viewport).
  *
+ * @property {(layerIds: string[]) => any[]} getVisibleFeatures
+ * Return all GeoJSON features currently visible in the viewport on the given layers,
+ * respecting layer visibility and any active filters. Returns [] if unsupported.
+ *
  * @property {() => string} getAreaDimensions
  * Get the dimensions of the visible map area as a formatted string (e.g., '400m by 750m').
  *
@@ -236,7 +284,7 @@
  * @property {(point: { x: number, y: number }) => [number, number]} screenToMap
  * Convert screen pixel position (x from left edge, y from top edge of viewport) to map coordinates ([lng, lat] or [easting, northing] depending on the crs of the map provider).
  *
- * @property {(selectedFeatures: any[], stylesMap: any) => any} [updateHighlightedFeatures]
+ * @property {(selectedFeatures: any[], activeFeatures: any[], stylesMap: any) => any} [updateHighlightedFeatures]
  * @experimental Update highlighted features on the map.
  *
  * @property {(direction: string) => any} [highlightNextLabel]
@@ -262,6 +310,19 @@
  * Coordinate reference system.
  */
 
+/**
+ * Configuration options for the MapLibre provider.
+ *
+ * @typedef {Object} MaplibreProviderConfig
+ *
+ * @property {string} [workerUrl]
+ * URL to a separately hosted MapLibre worker file (`maplibre-gl-csp-worker.js`).
+ * Required when running under a Content Security Policy that blocks `blob:` worker
+ * URLs. The file ships with maplibre-gl and must be served from your own origin.
+ * When set, MapLibre loads the worker from this URL instead of generating an
+ * inline blob, so your CSP only needs `worker-src 'self'`.
+ */
+
 /**
  * Descriptor for lazy-loading a map provider.
  *
@@ -316,7 +377,7 @@
  * Alt text for logo.
  *
  * @property {'light' | 'dark'} [mapColorScheme]
- * Map colour scheme. Sets the default values of `haloColor`, `selectedColor`, and `foregroundColor`
+ * Map colour scheme. Sets the default values of `haloColor`, `selectedColor`, `activeColor`, 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.
  *
@@ -329,10 +390,14 @@
  * 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.
+ * Theme colour for committed selection — 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} [activeColor]
+ * Theme colour for the active (keyboard cursor) state — the focus ring shown when navigating features
+ * with the keyboard. Falls back to `#ffdd00` for both light and dark schemes.
+ *
  * @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).
@@ -354,7 +419,7 @@
  * @property {string} [symbolSvgContent]
  * Default inner SVG path content. When set, overrides `symbol`.
  *
- * @property {string} [viewBox='0 0 38 38']
+ * @property {string} [viewBox='0 0 44 44']
  * Default SVG viewBox.
  *
  * @property {[number, number]} [anchor=[0.5, 0.5]]
@@ -366,15 +431,10 @@
  * @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.
  */
 
 /**
@@ -407,8 +467,8 @@
  * 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'`.
+ * SVG viewBox attribute for the symbol, e.g. `'0 0 44 44'`.
+ * Defaults to the registered symbol's viewBox, or `'0 0 44 44'`.
  *
  * @property {[number, number]} [anchor]
  * Anchor point as a normalised [x, y] pair where [0, 0] is top-left and [1, 1] is bottom-right.
@@ -421,9 +481,6 @@
  * @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
@@ -434,6 +491,14 @@
  * import { graphics } from './config/symbolConfig.js'
  * markers.add('id', coords, { symbol: 'pin', graphic: graphics.cross })
  *
+ * @property {string} [label]
+ * Plain-text label for this marker. Used as the accessible name on the marker SVG, and rendered
+ * as a visible label bubble when `showLabel` is `true` or when `symbol` is `null` (standalone label).
+ *
+ * @property {boolean} [showLabel=false]
+ * Whether to render a visible label bubble above the marker symbol. Defaults to `false`.
+ * Set `symbol` to `null` instead to create a standalone label with no symbol.
+ *
  */
 
 /**
@@ -444,6 +509,11 @@
  * @property {PanelBreakpointConfig} desktop
  * Desktop breakpoint configuration.
  *
+ * @property {boolean} [focus=true]
+ * Whether to move focus to the panel when it opens. Set to false to prevent the panel from
+ * receiving focus — useful for panels present on page load or panels that should not interrupt
+ * the user's current flow. Modal panels always receive focus regardless of this setting.
+ *
  * @property {string} [html]
  * HTML content.
  *
@@ -621,8 +691,15 @@
  * @property {MapStyleConfig} [mapStyle]
  * Map style configuration.
  *
- * @property {string} [mapViewParamKey='mv']
- * URL query parameter key used to control map view state.
+ * @property {string} [mapViewQueryParam='mv']
+ * URL query parameter used to control fullscreen/hybrid/buttonFirst state.
+ * Override if the default value clashes with an existing parameter on your page.
+ *
+ * @property {'sync' | 'readOnly' | 'none'} [urlPosition='sync']
+ * Controls how map center and zoom interact with the page URL.
+ *   - `'sync'` — reads on load and writes on pan/zoom (default)
+ *   - `'readOnly'` — seeds the initial view from the URL but never writes back
+ *   - `'none'` — ignores the URL entirely; use when you don't want the user's pan/zoom to be persisted or shared
  *
  * @property {MarkerConfig[]} [markers]
  * Initial markers to display on the map.

package/src/utils/constrainKeyboardFocus.js

@@ -4,11 +4,11 @@ export function constrainKeyboardFocus (containerEl, e) {
   }
 
   const selectors = [
-    'a[href]:not([disabled])',
-    'button:not([disabled])',
-    'textarea:not([disabled])',
-    'input:not([disabled])',
-    'select:not([disabled])',
+    'a[href]:not([disabled]):not([tabindex="-1"])',
+    'button:not([disabled]):not([tabindex="-1"])',
+    'textarea:not([disabled]):not([tabindex="-1"])',
+    'input:not([disabled]):not([tabindex="-1"])',
+    'select:not([disabled]):not([tabindex="-1"])',
     '*[tabindex="0"]:not([disabled])'
   ]
   let focusableEls = Array.from(containerEl.querySelectorAll(selectors.join(',')))

package/src/utils/detectInterfaceType.js

@@ -1,5 +1,6 @@
 let lastInterfaceType = window.matchMedia('(pointer: coarse)').matches ? 'touch' : 'unknown'
 const interfaceTypeListeners = new Set()
+const interfaceTypeImmediateListeners = new Set()
 
 // -----------------------------------------------------------------------------
 // Internal (not exported)
@@ -20,9 +21,8 @@ function normalizePointerType (pointerType) {
 function notifyListeners (newType) {
   if (lastInterfaceType !== newType) {
     lastInterfaceType = newType
-    interfaceTypeListeners.forEach((listener) => {
-      listener(newType)
-    })
+    interfaceTypeImmediateListeners.forEach(listener => listener(newType))
+    interfaceTypeListeners.forEach(listener => listener(newType))
   }
 }
 
@@ -44,7 +44,18 @@ function createInterfaceDetector () {
 
   const handlePointer = event => {
     const type = normalizePointerType(event.pointerType)
-    setTimeout(() => notifyListeners(type), REACT_CLICK_DELAY)
+    if (type === lastInterfaceType) {
+      return
+    }
+    // Update synchronously so getInterfaceType() returns the new value immediately —
+    // this prevents focusin handlers from seeing the stale 'keyboard' type during a
+    // pointer-triggered focus move. Listeners (React state) are still notified async
+    // to avoid layout thrashing during the click event.
+    lastInterfaceType = type
+    interfaceTypeImmediateListeners.forEach(listener => listener(type))
+    setTimeout(() => {
+      interfaceTypeListeners.forEach(listener => listener(type))
+    }, REACT_CLICK_DELAY)
   }
 
   const handleKeyDown = e => {
@@ -81,8 +92,19 @@ function subscribeToInterfaceChanges (onInterfaceTypeChange) {
   }
 }
 
+// Fires synchronously within the same event cycle — use for direct DOM updates
+// that need to be in sync with the pointer event (no 150ms React delay).
+function subscribeToInterfaceChangesImmediate (onInterfaceTypeChange) {
+  interfaceTypeImmediateListeners.add(onInterfaceTypeChange)
+
+  return () => {
+    interfaceTypeImmediateListeners.delete(onInterfaceTypeChange)
+  }
+}
+
 export {
   createInterfaceDetector,
   getInterfaceType,
-  subscribeToInterfaceChanges
+  subscribeToInterfaceChanges,
+  subscribeToInterfaceChangesImmediate
 }

package/src/utils/detectInterfaceType.test.js

@@ -54,7 +54,7 @@ const triggerDomEvent = (event, payload) => {
 
 // --- TEST SUITE ---
 describe('Interface Detector Utility Module', () => {
-  let createInterfaceDetector, getInterfaceType, subscribeToInterfaceChanges
+  let createInterfaceDetector, getInterfaceType, subscribeToInterfaceChanges, subscribeToInterfaceChangesImmediate
   let cleanup
 
   beforeEach(async () => {
@@ -72,6 +72,7 @@ describe('Interface Detector Utility Module', () => {
     createInterfaceDetector = importedModule.createInterfaceDetector
     getInterfaceType = importedModule.getInterfaceType
     subscribeToInterfaceChanges = importedModule.subscribeToInterfaceChanges
+    subscribeToInterfaceChangesImmediate = importedModule.subscribeToInterfaceChangesImmediate
 
     Object.keys(eventListeners).forEach(key => delete eventListeners[key])
     Object.keys(mediaListeners).forEach(key => delete mediaListeners[key])
@@ -99,18 +100,21 @@ describe('Interface Detector Utility Module', () => {
 
     // --- Path 1a: pointerdown 'touch' ---
     triggerDomEvent('pointerdown', { pointerType: 'touch' })
+    expect(getInterfaceType()).toBe('touch') // synchronous update
+    expect(handler).not.toHaveBeenCalled() // listener still pending
     jest.advanceTimersByTime(150)
-    expect(getInterfaceType()).toBe('touch')
     expect(handler).toHaveBeenCalledWith('touch')
     handler.mockClear()
 
     // --- Path 1b: pointerdown 'pen' ---
     triggerDomEvent('pointerdown', { pointerType: 'pen' })
     jest.advanceTimersByTime(150)
-    expect(handler).not.toHaveBeenCalled()
+    expect(handler).not.toHaveBeenCalled() // 'pen' normalises to 'touch' — no change
 
     // --- Path 1c: pointerdown 'mouse' ---
     triggerDomEvent('pointerdown', { pointerType: 'mouse' })
+    expect(getInterfaceType()).toBe('mouse') // synchronous update
+    expect(handler).not.toHaveBeenCalled() // listener still pending
     jest.advanceTimersByTime(150)
     expect(getInterfaceType()).toBe('mouse')
     expect(handler).toHaveBeenCalledWith('mouse')
@@ -129,6 +133,10 @@ describe('Interface Detector Utility Module', () => {
     expect(handler).toHaveBeenCalledWith('keyboard')
     handler.mockClear()
 
+    // Tab again when already keyboard — notifyListeners no-op branch
+    triggerDomEvent('keydown', { key: 'Tab' })
+    expect(handler).not.toHaveBeenCalled()
+
     // keydown with non-Tab
     triggerDomEvent('keydown', { key: 'a' })
     expect(handler).not.toHaveBeenCalled()
@@ -152,6 +160,24 @@ describe('Interface Detector Utility Module', () => {
     expect(handler).not.toHaveBeenCalled()
   })
 
+  it('subscribeToInterfaceChangesImmediate fires synchronously and unsubscribes', () => {
+    const handler = jest.fn()
+    const unsubscribe = subscribeToInterfaceChangesImmediate(handler)
+    cleanup = createInterfaceDetector()
+
+    triggerDomEvent('pointerdown', { pointerType: 'touch' })
+    expect(handler).toHaveBeenCalledWith('touch') // fires before timer advance
+
+    // Tab keydown goes through notifyListeners — exercises immediate forEach callback
+    triggerDomEvent('keydown', { key: 'Tab' })
+    expect(handler).toHaveBeenCalledWith('keyboard')
+    expect(handler).toHaveBeenCalledTimes(2)
+
+    unsubscribe()
+    triggerDomEvent('pointerdown', { pointerType: 'mouse' })
+    expect(handler).toHaveBeenCalledTimes(2) // no longer called after unsubscribe
+  })
+
   it('should return "touch" when matchMedia initially matches coarse pointer', async () => {
     jest.resetModules()
 

package/src/utils/mapStateSync.js

@@ -72,8 +72,8 @@ const setMapStateInURL = (id, state, currentHref = window.location.href) => {
  * @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) => {
-  const savedState = getMapStateFromURL(id, search)
+const getInitialMapState = ({ id, center, zoom, bounds, urlPosition = 'sync' }, search = window.location.search) => {
+  const savedState = urlPosition === 'none' ? null : getMapStateFromURL(id, search)
   if (savedState) {
     return {
       center: savedState.center,

package/src/utils/mapStateSync.test.js

@@ -30,6 +30,24 @@ describe('mapStateSync utilities', () => {
       const state = getInitialMapState({ id: 'map1', bounds }, '')
       expect(state.bounds).toEqual(bounds)
     })
+
+    it('ignores URL params when urlPosition is none', () => {
+      const state = getInitialMapState(
+        { id: 'map1', center: [1, 2], zoom: 3, urlPosition: 'none' },
+        '?map1:center=10,20&map1:zoom=5'
+      )
+      expect(state.center).toEqual([1, 2])
+      expect(state.zoom).toBe(3)
+    })
+
+    it('reads URL params when urlPosition is readOnly', () => {
+      const state = getInitialMapState(
+        { id: 'map1', center: [1, 2], zoom: 3, urlPosition: 'readOnly' },
+        '?map1:center=10,20&map1:zoom=5'
+      )
+      expect(state.center).toEqual([10, 20])
+      expect(state.zoom).toBe(5)
+    })
   })
 
   describe('setMapStateInURL', () => {

package/src/utils/patternUtils.js

@@ -1,7 +1,9 @@
-import { getValueForStyle } from '../utils/getValueForStyle.js'
-
 // Border path rendered behind the pattern content in Key panel symbols (20×20 coordinate space).
 export const KEY_BORDER_PATH = '<path d="M19 2.862v14.275c0 1.028-.835 1.862-1.862 1.862H2.863c-1.028 0-1.862-.835-1.862-1.862V2.862C1.001 1.834 1.836 1 2.863 1h14.275C18.166 1 19 1.835 19 2.862z" fill="{{backgroundColor}}" stroke="{{foregroundColor}}" stroke-width="2"/>'
+// Minimum oversampling — keeps 16×16 physical pixels as the floor so patterns remain crisp.
+const PATTERN_MIN_PIXEL_RATIO = 2
+
+export const getEffectivePixelRatio = (pixelRatio) => Math.max(PATTERN_MIN_PIXEL_RATIO, pixelRatio * 2)
 
 export const hashString = (str) => {
   let hash = 0
@@ -32,68 +34,3 @@ export const injectColors = (content, foregroundColor, backgroundColor) =>
  * @returns {boolean}
  */
 export const hasPattern = (dataset) => !!(dataset.fillPattern || dataset.fillPatternSvgContent)
-
-/**
- * Returns the raw (un-coloured) inner SVG content for a dataset's pattern.
- * Precedence: inline fillPatternSvgContent → named fillPattern from registry.
- *
- * @param {Object} dataset
- * @param {Object} patternRegistry
- * @returns {string|null}
- */
-export const getPatternInnerContent = (dataset, patternRegistry) => {
-  if (dataset.fillPatternSvgContent) {
-    return dataset.fillPatternSvgContent
-  }
-  if (dataset.fillPattern) {
-    return patternRegistry?.get(dataset.fillPattern)?.svgContent ?? null
-  }
-  return null
-}
-
-/**
- * Returns a deterministic image ID for a pattern + resolved colour + pixel ratio combination.
- *
- * @param {Object} dataset
- * @param {string} mapStyleId
- * @param {Object} patternRegistry
- * @param {number} [pixelRatio=1]
- * @returns {string|null}
- */
-// Minimum oversampling — keeps 16×16 physical pixels as the floor so patterns remain crisp.
-export const PATTERN_MIN_PIXEL_RATIO = 2
-
-export const getPatternImageId = (dataset, mapStyleId, patternRegistry, pixelRatio = 1) => {
-  const innerContent = getPatternInnerContent(dataset, patternRegistry)
-  if (!innerContent) {
-    return null
-  }
-  const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
-  const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
-  const effectiveRatio = Math.max(PATTERN_MIN_PIXEL_RATIO, pixelRatio)
-  return `pattern-${hashString(innerContent + fg + bg)}-${effectiveRatio}x`
-}
-
-/**
- * Returns colour-injected SVG path content for use in Key panel pattern symbols.
- * Returns { border, content } where border is the rounded-rect outline and content
- * is the pattern fill. Returns null if the dataset has no pattern.
- *
- * @param {Object} dataset
- * @param {string} mapStyleId
- * @param {Object} patternRegistry
- * @returns {{ border: string, content: string }|null}
- */
-export const getKeyPatternPaths = (dataset, mapStyleId, patternRegistry) => {
-  const innerContent = getPatternInnerContent(dataset, patternRegistry)
-  if (!innerContent) {
-    return null
-  }
-  const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
-  const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
-  const borderStroke = getValueForStyle(dataset.stroke, mapStyleId) || fg
-  return {
-    border: injectColors(KEY_BORDER_PATH, borderStroke, bg),
-    content: injectColors(innerContent, fg, bg)
-  }
-}

package/src/utils/patternUtils.test.js

@@ -1,17 +1,9 @@
 import {
   hashString,
   injectColors,
-  hasPattern,
-  getPatternInnerContent,
-  getPatternImageId,
-  getKeyPatternPaths,
-  KEY_BORDER_PATH
+  hasPattern
 } from './patternUtils.js'
 
-const mockRegistry = {
-  get: (id) => id === 'dot' ? { id: 'dot', svgContent: '<path d="M4 4" fill="{{foregroundColor}}"/>' } : undefined
-}
-
 describe('hashString', () => {
   test('returns a non-empty string', () => {
     expect(typeof hashString('hello')).toBe('string')
@@ -61,117 +53,3 @@ describe('hasPattern', () => {
     expect(hasPattern({ fill: 'red' })).toBe(false)
   })
 })
-
-describe('getPatternInnerContent', () => {
-  test('returns fillPatternSvgContent when set (inline SVG takes precedence)', () => {
-    const dataset = { fillPatternSvgContent: '<path d="custom"/>', fillPattern: 'dot' }
-    expect(getPatternInnerContent(dataset, mockRegistry)).toBe('<path d="custom"/>')
-  })
-
-  test('returns svgContent from registry for a named fillPattern', () => {
-    const dataset = { fillPattern: 'dot' }
-    expect(getPatternInnerContent(dataset, mockRegistry)).toBe('<path d="M4 4" fill="{{foregroundColor}}"/>')
-  })
-
-  test('returns null for an unregistered fillPattern name', () => {
-    const dataset = { fillPattern: 'unknown-pattern' }
-    expect(getPatternInnerContent(dataset, mockRegistry)).toBeNull()
-  })
-
-  test('returns null when no pattern is configured', () => {
-    expect(getPatternInnerContent({}, mockRegistry)).toBeNull()
-  })
-})
-
-describe('getPatternImageId', () => {
-  test('returns a deterministic string id', () => {
-    const dataset = { fillPattern: 'dot', fillPatternForegroundColor: 'red', fillPatternBackgroundColor: 'blue' }
-    const id = getPatternImageId(dataset, 'style-a', mockRegistry)
-    expect(typeof id).toBe('string')
-    expect(id).toMatch(/^pattern-/)
-    expect(id).toBe(getPatternImageId(dataset, 'style-a', mockRegistry))
-  })
-
-  test('returns null when no pattern content is found', () => {
-    expect(getPatternImageId({ fillPattern: 'unknown' }, 'style-a', mockRegistry)).toBeNull()
-  })
-
-  test('produces different ids for different colours', () => {
-    const base = { fillPattern: 'dot' }
-    const idA = getPatternImageId({ ...base, fillPatternForegroundColor: 'red' }, 'style-a', mockRegistry)
-    const idB = getPatternImageId({ ...base, fillPatternForegroundColor: 'blue' }, 'style-a', mockRegistry)
-    expect(idA).not.toBe(idB)
-  })
-
-  test('floors effective ratio at PATTERN_MIN_PIXEL_RATIO so low-DPI ids match 2x', () => {
-    const dataset = { fillPattern: 'dot' }
-    const id1x = getPatternImageId(dataset, 'style-a', mockRegistry, 1)
-    const id2x = getPatternImageId(dataset, 'style-a', mockRegistry, 2)
-    expect(id1x).toBe(id2x)
-    expect(id1x).toMatch(/-2x$/)
-  })
-
-  test('produces different ids for pixelRatios above the floor', () => {
-    const dataset = { fillPattern: 'dot' }
-    const id2x = getPatternImageId(dataset, 'style-a', mockRegistry, 2)
-    const id3x = getPatternImageId(dataset, 'style-a', mockRegistry, 3)
-    expect(id2x).not.toBe(id3x)
-    expect(id2x).toMatch(/-2x$/)
-    expect(id3x).toMatch(/-3x$/)
-  })
-
-  test('falls back to "black" foreground and "transparent" background when colours are absent', () => {
-    const id = getPatternImageId({ fillPattern: 'dot' }, 'style-a', mockRegistry)
-    const idExplicit = getPatternImageId(
-      { fillPattern: 'dot', fillPatternForegroundColor: 'black', fillPatternBackgroundColor: 'transparent' },
-      'style-a',
-      mockRegistry
-    )
-    expect(id).toBe(idExplicit)
-  })
-})
-
-describe('getKeyPatternPaths', () => {
-  test('returns border and content strings with colours injected', () => {
-    const dataset = {
-      fillPattern: 'dot',
-      fillPatternForegroundColor: 'red',
-      fillPatternBackgroundColor: 'white',
-      stroke: 'black'
-    }
-    const result = getKeyPatternPaths(dataset, 'style-a', mockRegistry)
-    expect(result).not.toBeNull()
-    expect(result.border).toContain('black') // stroke colour
-    expect(result.border).toContain('white') // background colour
-    expect(result.content).toContain('red') // foreground colour
-    expect(result.border).not.toContain('{{foregroundColor}}')
-    expect(result.content).not.toContain('{{foregroundColor}}')
-  })
-
-  test('returns null when no pattern content is found', () => {
-    expect(getKeyPatternPaths({ fillPattern: 'unknown' }, 'style-a', mockRegistry)).toBeNull()
-  })
-
-  test('falls back to "black" fg and "transparent" bg when colour properties are absent', () => {
-    const result = getKeyPatternPaths({ fillPattern: 'dot' }, 'style-a', mockRegistry)
-    expect(result).not.toBeNull()
-    expect(result.content).toContain('black')
-    expect(result.border).toContain('transparent')
-  })
-
-  test('border stroke falls back to foreground colour when stroke is absent', () => {
-    const result = getKeyPatternPaths(
-      { fillPattern: 'dot', fillPatternForegroundColor: 'green' },
-      'style-a',
-      mockRegistry
-    )
-    expect(result).not.toBeNull()
-    // borderStroke falls back to fg ('green'), so the border uses green for both stroke and background
-    expect(result.border).toContain('green')
-  })
-
-  test('KEY_BORDER_PATH contains foregroundColor and backgroundColor tokens', () => {
-    expect(KEY_BORDER_PATH).toContain('{{foregroundColor}}')
-    expect(KEY_BORDER_PATH).toContain('{{backgroundColor}}')
-  })
-})

package/src/utils/symbolUtils.js

@@ -14,23 +14,21 @@ const SYMBOL_STYLE_PROPS = new Set([
 export const hasSymbol = (dataset) => !!(dataset.symbol || dataset.symbolSvgContent)
 
 /**
- * Resolves the symbolDef for a dataset's symbol config.
+ * Returns true if a marker item should render as a standalone label with no symbol.
+ * Requires label content and at least one of symbol/symbolSvgContent to be explicitly null.
+ * Undefined values fall through to render-time default symbol resolution.
  *
- * dataset.symbol is a string symbol ID (e.g. 'pin').
- * dataset.symbolSvgContent is inline SVG content for a custom symbol.
- *
- * @param {Object} dataset
- * @param {Object} symbolRegistry
- * @returns {Object|undefined}
+ * @param {Object} marker
+ * @returns {boolean}
  */
-export const getSymbolDef = (dataset, symbolRegistry) => {
-  if (dataset.symbolSvgContent) {
-    return { svg: dataset.symbolSvgContent }
+export const isStandaloneLabel = (marker) => {
+  if (!marker.label) {
+    return false
   }
-  if (dataset.symbol) {
-    return symbolRegistry.get(dataset.symbol)
+  if (marker.symbol || marker.symbolSvgContent) {
+    return false
   }
-  return undefined
+  return marker.symbol === null || marker.symbolSvgContent === null
 }
 
 /**