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

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').
  */
 
 /**
@@ -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].

package/src/utils/getSafeZoneInset.js

@@ -27,7 +27,7 @@
  * @param {React.RefObject}  refs.leftRef          - Left button column.
  * @param {React.RefObject}  refs.rightRef         - Right button column.
  * @param {React.RefObject}  refs.actionsRef       - Bottom action bar.
- * @param {React.RefObject}  refs.footerRef        - Footer (logo, copyright, etc).
+ * @param {React.RefObject}  refs.bottomRef        - Bottom row (logo, copyright, etc).
  * @param {React.RefObject} [refs.leftTopRef]      - Top-left panel slot.
  * @param {React.RefObject} [refs.leftBottomRef]   - Bottom-left panel slot.
  * @param {React.RefObject} [refs.rightTopRef]     - Top-right panel slot.
@@ -107,15 +107,15 @@ const computeRow = (leftW, rightW, leftH, rightH, wThreshold, baseInset, gap) =>
   leftW + rightW > wThreshold ? baseInset + Math.max(leftH, rightH) + gap : 0
 
 export const getSafeZoneInset = ({
-  mainRef, leftRef, rightRef, actionsRef, footerRef,
+  mainRef, leftRef, rightRef, actionsRef, bottomRef,
   leftTopRef, leftBottomRef, rightTopRef, rightBottomRef
 }) => {
-  if ([mainRef, leftRef, rightRef, actionsRef, footerRef].some(ref => !ref?.current)) {
+  if ([mainRef, leftRef, rightRef, actionsRef, bottomRef].some(ref => !ref?.current)) {
     return undefined
   }
 
   const main = mainRef.current; const left = leftRef.current
-  const actions = actionsRef.current; const footer = footerRef.current
+  const actions = actionsRef.current; const bottom = bottomRef.current
 
   const gap = Number.parseInt(getComputedStyle(document.documentElement).getPropertyValue('--divider-gap'), 10)
 
@@ -127,8 +127,10 @@ export const getSafeZoneInset = ({
   const baseLeft = main.offsetLeft + left.offsetLeft + colWidth + gap
   const baseRight = left.offsetLeft + colWidth + gap
   const baseTop = left.offsetTop
-  const footerInset = main.offsetHeight - footer.offsetTop + gap // mirrors --left/right-offset-bottom CSS var
-  const baseBottom = Math.max(main.offsetHeight - actions.offsetTop + gap, footerInset)
+  const bottomContainerPad = main.offsetHeight - bottom.offsetTop - bottom.offsetHeight
+  // Minimum: primary-gap above the bottom edge. Normally: divider-gap above the top of the bottom container.
+  const bottomInset = Math.max(bottomContainerPad, main.offsetHeight - bottom.offsetTop + gap)
+  const baseBottom = Math.max(main.offsetHeight - actions.offsetTop + gap, bottomInset)
 
   const availableH = main.offsetHeight - baseTop - baseBottom
   const availableW = main.offsetWidth - (baseLeft - main.offsetLeft) - baseRight
@@ -139,7 +141,7 @@ export const getSafeZoneInset = ({
   const leftPanelInset = leftCol.panelInset
   const rightPanelInset = rightCol.panelInset
   const topPanelInset = computeRow(leftCol.rowA.w, rightCol.rowA.w, leftCol.rowA.h, rightCol.rowA.h, availableW / RATIO, baseTop, gap)
-  const bottomPanelInset = computeRow(leftCol.rowB.w, rightCol.rowB.w, leftCol.rowB.h, rightCol.rowB.h, availableW / RATIO, footerInset, gap)
+  const bottomPanelInset = computeRow(leftCol.rowB.w, rightCol.rowB.w, leftCol.rowB.h, rightCol.rowB.h, availableW / RATIO, bottomInset, gap)
 
   const usableW = main.offsetWidth - 2 * gap
   const usableH = main.offsetHeight - 2 * gap

package/src/utils/getSafeZoneInset.test.js

@@ -7,7 +7,7 @@ const LEFT_WIDTH = 40
 const LEFT_TOP = 60
 const RIGHT_WIDTH = 40
 const ACTIONS_TOP = 540
-const FOOTER_TOP = 560
+const BOTTOM_TOP = 560
 const EARLY_ACTIONS_TOP = 500
 const GAP = 8
 
@@ -31,7 +31,7 @@ const PANEL_H_TALL = 150
 const PANEL_H_SHORT = 100
 
 const ABOVE_CAP_TOP = 330 // 60+330+8=398 > CAP_HEIGHT ≈ 389.3 → capped
-const FOOTER_INSET = MAIN_HEIGHT - FOOTER_TOP + GAP // 48
+const BOTTOM_INSET = MAIN_HEIGHT - BOTTOM_TOP + GAP // 48: divider-gap above top of bottom container
 const ABOVE_CAP_BOTTOM = 342 // 48+342+8=398 > CAP_HEIGHT → capped
 
 const PANEL_W_STANDARD = 200
@@ -49,7 +49,7 @@ const CAP_HEIGHT = (MAIN_HEIGHT - 2 * GAP) * (MAX_RATIO - 1) / MAX_RATIO
 
 // ─── Setup ──────────────────────────────────────────────────────────────────
 
-let mainRef, leftRef, rightRef, actionsRef, footerRef
+let mainRef, leftRef, rightRef, actionsRef, bottomRef
 
 beforeAll(() => {
   globalThis.getComputedStyle = jest.fn().mockReturnValue({ getPropertyValue: () => String(GAP) })
@@ -72,10 +72,10 @@ beforeEach(() => {
   leftRef = colRef(LEFT_WIDTH, LEFT_LEFT, LEFT_TOP)
   rightRef = colRef(RIGHT_WIDTH)
   actionsRef = { current: { offsetTop: ACTIONS_TOP } }
-  footerRef = { current: { offsetTop: FOOTER_TOP } }
+  bottomRef = { current: { offsetTop: BOTTOM_TOP, offsetHeight: 0 } }
 })
 
-const base = () => ({ mainRef, leftRef, rightRef, actionsRef, footerRef })
+const base = () => ({ mainRef, leftRef, rightRef, actionsRef, bottomRef })
 
 // Slot container where an .im-c-panel is the first element child.
 const panel = (offsetWidth, offsetHeight) => {
@@ -96,7 +96,7 @@ describe('getSafeZoneInset — missing refs', () => {
     expect(getSafeZoneInset({ ...base(), leftRef: { current: null } })).toBeUndefined()
   })
   it('returns undefined when actionsRef is undefined', () => {
-    expect(getSafeZoneInset({ mainRef, leftRef, rightRef, footerRef })).toBeUndefined()
+    expect(getSafeZoneInset({ mainRef, leftRef, rightRef, bottomRef })).toBeUndefined()
   })
 })
 
@@ -120,7 +120,7 @@ describe('getSafeZoneInset — base structural insets', () => {
   it('uses zero button width when column ref has no button group', () => {
     const noGroupLeft = { current: { offsetWidth: 0, offsetLeft: LEFT_LEFT, offsetTop: LEFT_TOP, querySelector: () => null } }
     const noGroupRight = { current: { offsetWidth: 0, offsetLeft: 0, offsetTop: 0, querySelector: () => null } }
-    expect(getSafeZoneInset({ mainRef, leftRef: noGroupLeft, rightRef: noGroupRight, actionsRef, footerRef })).toEqual({
+    expect(getSafeZoneInset({ mainRef, leftRef: noGroupLeft, rightRef: noGroupRight, actionsRef, bottomRef })).toEqual({
       left: LEFT_LEFT + GAP, right: LEFT_LEFT + GAP, top: LEFT_TOP, bottom: BASE_BOTTOM
     })
   })
@@ -133,7 +133,7 @@ describe('getSafeZoneInset — base structural insets', () => {
       rightBottomRef: panel(PANEL_W_STANDARD, 0)
     })).toEqual({ left: BASE_LEFT, right: BASE_RIGHT, top: BASE_TOP, bottom: BASE_BOTTOM })
   })
-  it('uses max of actions and footer for base bottom', () => {
+  it('uses max of actions and bottom for base bottom', () => {
     actionsRef.current.offsetTop = EARLY_ACTIONS_TOP
     expect(getSafeZoneInset(base()).bottom).toBe(MAIN_HEIGHT - EARLY_ACTIONS_TOP + GAP)
   })
@@ -244,7 +244,7 @@ describe('getSafeZoneInset — bottom edge', () => {
   })
   it('triggers when a bottom panel width exceeds threshold', () => {
     expect(getSafeZoneInset({ ...base(), leftBottomRef: panel(ABOVE_W_THRESHOLD, ABOVE_THRESHOLD) }).bottom)
-      .toBe(Math.min(FOOTER_INSET + ABOVE_THRESHOLD + GAP, CAP_HEIGHT))
+      .toBe(Math.min(BOTTOM_INSET + ABOVE_THRESHOLD + GAP, CAP_HEIGHT))
   })
   it('column-primary wide-and-tall bottom panel triggers left inset, not bottom', () => {
     // panel(400,342): h/availableH≈0.724 > w/availableW≈0.510 → column-primary
@@ -257,7 +257,7 @@ describe('getSafeZoneInset — bottom edge', () => {
       ...base(),
       leftBottomRef: panel(COMBINED_ABOVE_W, PANEL_H_TALL),
       rightBottomRef: panel(COMBINED_ABOVE_W, PANEL_H_SHORT)
-    }).bottom).toBe(Math.min(FOOTER_INSET + PANEL_H_TALL + GAP, CAP_HEIGHT))
+    }).bottom).toBe(Math.min(BOTTOM_INSET + PANEL_H_TALL + GAP, CAP_HEIGHT))
   })
   it('does not trigger when both bottom panels are below combined width threshold', () => {
     expect(getSafeZoneInset({

package/src/utils/patternUtils.js

@@ -0,0 +1,94 @@
+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"/>'
+
+export const hashString = (str) => {
+  let hash = 0
+  for (const ch of str) {
+    hash = ((hash << 5) - hash) + ch.codePointAt(0)
+    hash = hash & hash
+  }
+  return Math.abs(hash).toString(36) // NOSONAR: base36 encoding for compact alphanumeric hash string
+}
+
+/**
+ * Replaces {{foregroundColor}} and {{backgroundColor}} tokens in SVG content with resolved colour values.
+ *
+ * @param {string} content - SVG path string with colour tokens
+ * @param {string} foregroundColor
+ * @param {string} backgroundColor
+ * @returns {string}
+ */
+export const injectColors = (content, foregroundColor, backgroundColor) =>
+  content
+    .replace(/\{\{foregroundColor\}\}/g, foregroundColor || 'black')
+    .replace(/\{\{backgroundColor\}\}/g, backgroundColor || 'transparent')
+
+/**
+ * Returns true if a dataset/config has a fill pattern configured.
+ *
+ * @param {Object} dataset
+ * @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 combination.
+ *
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @param {Object} patternRegistry
+ * @returns {string|null}
+ */
+export const getPatternImageId = (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'
+  return `pattern-${hashString(innerContent + fg + bg)}`
+}
+
+/**
+ * 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)
+  }
+}