@defra/interactive-map 0.0.10-alpha → 0.0.12-alpha

package/src/App/store/appActionsMap.test.js

@@ -11,9 +11,10 @@ describe('actionsMap full coverage', () => {
 
   beforeEach(() => {
     const mockPanelConfig = {
-      panel1: { desktop: { exclusive: true, modal: false, initiallyOpen: true }, mobile: { exclusive: true, modal: false } },
+      panel1: { desktop: { exclusive: true, modal: false, open: true }, mobile: { exclusive: true, modal: false } },
       panel2: { desktop: { exclusive: false, modal: true }, mobile: { exclusive: false, modal: true } },
-      panel3: { desktop: { exclusive: false, modal: false }, mobile: { exclusive: false, modal: false } }
+      panel3: { desktop: { exclusive: false, modal: false }, mobile: { exclusive: false, modal: false } },
+      panel4: { desktop: { open: true, dismissible: false }, mobile: { open: true, dismissible: true } }
     }
 
     state = {
@@ -171,15 +172,15 @@ describe('actionsMap full coverage', () => {
     expect(result.panelConfig.panelX).toBeDefined()
   })
 
-  test('ADD_PANEL adds panelConfig and opens initiallyOpen panel', () => {
-    const payload = { id: 'panelY', config: { desktop: { initiallyOpen: true } } }
+  test('ADD_PANEL adds panelConfig and opens panel when open=true', () => {
+    const payload = { id: 'panelY', config: { desktop: { open: true } } }
     const result = actionsMap.ADD_PANEL(state, payload)
     expect(result.panelConfig.panelY).toBeDefined()
     expect(result.openPanels.panelY).toBeDefined()
   })
 
-  test('ADD_PANEL does not open if initiallyOpen false', () => {
-    const payload = { id: 'panelZ', config: { desktop: { initiallyOpen: false } } }
+  test('ADD_PANEL does not open if open=false', () => {
+    const payload = { id: 'panelZ', config: { desktop: { open: false } } }
     const result = actionsMap.ADD_PANEL(state, payload)
     expect(result.panelConfig.panelZ).toBeDefined()
     expect(result.openPanels.panelZ).toBeUndefined()
@@ -274,6 +275,31 @@ describe('actionsMap full coverage', () => {
     expect(result.isFullscreen).toBe(true)
   })
 
+  test('SET_BREAKPOINT restores non-dismissible open panel at new breakpoint', () => {
+    const tmp = { ...state, openPanels: {} }
+    const result = actionsMap.SET_BREAKPOINT(tmp, { breakpoint: 'desktop', behaviour: 'responsive', hybridWidth: null, maxMobileWidth: 640 })
+    expect(result.openPanels.panel4).toBeDefined()
+  })
+
+  test('SET_BREAKPOINT does not force-open a non-dismissible panel where it is dismissible', () => {
+    const tmp = { ...state, openPanels: {} }
+    const result = actionsMap.SET_BREAKPOINT(tmp, { breakpoint: 'mobile', behaviour: 'responsive', hybridWidth: null, maxMobileWidth: 640 })
+    expect(result.openPanels.panel4).toBeUndefined()
+  })
+
+  test('SET_BREAKPOINT preserves existing props when restoring a non-dismissible panel', () => {
+    const props = { myProp: 'value' }
+    const tmp = { ...state, openPanels: { panel4: { props } } }
+    const result = actionsMap.SET_BREAKPOINT(tmp, { breakpoint: 'desktop', behaviour: 'responsive', hybridWidth: null, maxMobileWidth: 640 })
+    expect(result.openPanels.panel4.props).toEqual(props)
+  })
+
+  test('SET_BREAKPOINT uses panelRegistry.getPanelConfig() when panelConfig missing', () => {
+    const tmp = { ...state, panelConfig: undefined, openPanels: {} }
+    const result = actionsMap.SET_BREAKPOINT(tmp, { breakpoint: 'desktop', behaviour: 'responsive', hybridWidth: null, maxMobileWidth: 640 })
+    expect(result.openPanels.panel4).toBeDefined()
+  })
+
   test('SET_HYBRID_FULLSCREEN updates isFullscreen', () => {
     const tmp = { ...state, isFullscreen: false }
     const result = actionsMap.SET_HYBRID_FULLSCREEN(tmp, true)
@@ -294,7 +320,7 @@ describe('actionsMap full coverage', () => {
 
   test('ADD_PANEL skips registry if panelRegistry missing', () => {
     const tmp = { ...state, panelRegistry: undefined }
-    const payload = { id: 'panelY', config: { desktop: { initiallyOpen: true } } }
+    const payload = { id: 'panelY', config: { desktop: { open: true } } }
     const result = actionsMap.ADD_PANEL(tmp, payload)
     expect(result.panelConfig.panelY).toBeDefined()
     expect(result.openPanels.panelY).toBeDefined()

package/src/App/store/appDispatchMiddleware.js

@@ -1,5 +1,7 @@
 // src/App/store/dispatchMiddleware.js
 import { EVENTS as events } from '../../config/events.js'
+import { defaultPanelConfig } from '../../config/appConfig.js'
+import { deepMerge } from '../../utils/deepMerge.js'
 
 /**
  * Determines which panels were implicitly closed when opening a new panel
@@ -78,4 +80,21 @@ export function handleActionSideEffects (action, previousState, panelConfig, eve
       eventBus.emit(events.APP_PANEL_OPENED, { panelId, props })
     })
   }
+
+  if (type === 'ADD_PANEL') {
+    const { id, config } = payload
+    const mergedConfig = deepMerge(defaultPanelConfig, config)
+    const bpConfig = mergedConfig[previousState.breakpoint]
+    if (bpConfig?.open) {
+      queueMicrotask(() => {
+        const slot = bpConfig.slot
+        const { visibleGeometry } = mergedConfig
+        const eventPayload = { panelId: id, slot }
+        if (visibleGeometry) {
+          eventPayload.visibleGeometry = visibleGeometry
+        }
+        eventBus.emit(events.APP_PANEL_OPENED, eventPayload)
+      })
+    }
+  }
 }

package/src/App/store/appDispatchMiddleware.test.js

@@ -177,4 +177,60 @@ describe('appDispatchMiddleware', () => {
       )
     })
   })
+
+  describe('ADD_PANEL', () => {
+    it('emits APP_PANEL_OPENED with slot when panel opens by default', async () => {
+      run(
+        { type: 'ADD_PANEL', payload: { id: 'newPanel', config: {} } },
+        { breakpoint: 'desktop' }
+      )
+
+      await flushMicrotasks()
+
+      expect(eventBus.emit).toHaveBeenCalledWith(
+        events.APP_PANEL_OPENED,
+        { panelId: 'newPanel', slot: 'inset' }
+      )
+    })
+
+    it('emits APP_PANEL_OPENED with visibleGeometry when provided in config', async () => {
+      const visibleGeometry = { type: 'Feature', geometry: { type: 'Point', coordinates: [1, 2] }, properties: {} }
+      run(
+        { type: 'ADD_PANEL', payload: { id: 'geoPanel', config: { visibleGeometry } } },
+        { breakpoint: 'desktop' }
+      )
+
+      await flushMicrotasks()
+
+      expect(eventBus.emit).toHaveBeenCalledWith(
+        events.APP_PANEL_OPENED,
+        { panelId: 'geoPanel', slot: 'inset', visibleGeometry }
+      )
+    })
+
+    it('does not emit APP_PANEL_OPENED when breakpoint config sets open: false', async () => {
+      run(
+        { type: 'ADD_PANEL', payload: { id: 'hiddenPanel', config: { desktop: { open: false } } } },
+        { breakpoint: 'desktop' }
+      )
+
+      await flushMicrotasks()
+
+      expect(eventBus.emit).not.toHaveBeenCalled()
+    })
+
+    it('emits APP_PANEL_OPENED with slot for mobile breakpoint', async () => {
+      run(
+        { type: 'ADD_PANEL', payload: { id: 'mobilePanel', config: {} } },
+        { breakpoint: 'mobile' }
+      )
+
+      await flushMicrotasks()
+
+      expect(eventBus.emit).toHaveBeenCalledWith(
+        events.APP_PANEL_OPENED,
+        { panelId: 'mobilePanel', slot: 'bottom' }
+      )
+    })
+  })
 })

package/src/App/store/mapActionsMap.js

@@ -7,13 +7,10 @@ const mergePayload = (state, payload) => ({
   ...payload
 })
 
-const setMapReady = (state, mapProvider) => {
-  return {
-    ...state,
-    isMapReady: true,
-    mapProvider
-  }
-}
+const setMapReady = (state) => ({
+  ...state,
+  isMapReady: true
+})
 
 const setMapStyle = (state, payload) => {
   return {

package/src/InteractiveMap/InteractiveMap.js

@@ -404,4 +404,22 @@ export default class InteractiveMap {
   addControl (id, config) {
     this.eventBus.emit(events.APP_ADD_CONTROL, { id, config })
   }
+
+  /**
+   * Fit the map view to a bounding box or GeoJSON geometry, respecting the safe zone padding.
+   *
+   * @param {[number, number, number, number] | object} target - Bounds as [west, south, east, north] or [minX, minY, maxX, maxY] depending on the crs, or a GeoJSON Feature, FeatureCollection, or geometry.
+   */
+  fitToBounds (target) {
+    this.eventBus.emit(events.MAP_FIT_TO_BOUNDS, target)
+  }
+
+  /**
+   * Set the map center and zoom, respecting the safe zone padding.
+   *
+   * @param {{ center?: [number, number], zoom?: number }} opts - View options.
+   */
+  setView (opts) {
+    this.eventBus.emit(events.MAP_SET_VIEW, opts)
+  }
 }

package/src/InteractiveMap/InteractiveMap.test.js

@@ -509,4 +509,16 @@ describe('InteractiveMap Public API Methods', () => {
       { id: 'btn-1', prop: 'disabled', value: true }
     )
   })
+
+  it('fitToBounds emits MAP_FIT_TO_BOUNDS with bbox', () => {
+    const bbox = [-0.489, 51.28, 0.236, 51.686]
+    map.fitToBounds(bbox)
+    expect(map.eventBus.emit).toHaveBeenCalledWith('map:fittobounds', bbox)
+  })
+
+  it('setView emits MAP_SET_VIEW with opts', () => {
+    const opts = { center: [-0.1276, 51.5074], zoom: 12 }
+    map.setView(opts)
+    expect(map.eventBus.emit).toHaveBeenCalledWith('map:setview', opts)
+  })
 })

package/src/config/appConfig.js

@@ -2,8 +2,8 @@ import { KeyboardHelp } from '../App/components/KeyboardHelp/KeyboardHelp.jsx'
 
 const keyboardBasePanelSlots = {
   slot: 'middle',
-  initiallyOpen: false,
-  dismissable: true,
+  open: false,
+  dismissible: true,
   modal: true
 }
 
@@ -42,7 +42,7 @@ export const defaultAppConfig = {
     desktop: buttonSlots
   }, {
     id: 'zoomIn',
-    group: 'zoom',
+    group: { name: 'zoom', label: 'Zoom controls', order: 0 },
     label: 'Zoom in',
     iconId: 'plus',
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomIn(appConfig.zoomDelta),
@@ -53,7 +53,7 @@ export const defaultAppConfig = {
     desktop: buttonSlots
   }, {
     id: 'zoomOut',
-    group: 'zoom',
+    group: { name: 'zoom', label: 'Zoom controls', order: 0 },
     label: 'Zoom out',
     iconId: 'minus',
     onClick: (_e, { mapProvider, appConfig }) => mapProvider.zoomOut(appConfig.zoomDelta),
@@ -99,7 +99,7 @@ export const defaultAppConfig = {
 // Used by addButton
 const defaultButtonSlots = {
   slot: 'right-top',
-  showLabel: false
+  showLabel: true
 }
 
 export const defaultButtonConfig = {
@@ -111,25 +111,27 @@ export const defaultButtonConfig = {
 
 // Used by addPanel
 export const defaultPanelConfig = {
-  showLabel: true,
   label: 'Panel',
   mobile: {
     slot: 'bottom',
-    initiallyOpen: true,
-    dismissable: true,
-    modal: false
+    open: true,
+    dismissible: true,
+    modal: false,
+    showLabel: true
   },
   tablet: {
     slot: 'inset',
-    initiallyOpen: true,
-    dismissable: true,
-    modal: false
+    open: true,
+    dismissible: true,
+    modal: false,
+    showLabel: true
   },
   desktop: {
     slot: 'inset',
-    initiallyOpen: true,
-    dismissable: true,
-    modal: false
+    open: true,
+    dismissible: true,
+    modal: false,
+    showLabel: true
   },
   render: null,
   html: null

package/src/config/events.js

@@ -87,12 +87,16 @@ export const EVENTS = {
   // Map commands (internal / plugin authors)
   // ============================================
 
-  /** @internal Set map style. Payload: styleId */
+  /** @internal Set map style. Payload: MapStyleConfig */
   MAP_SET_STYLE: 'map:setstyle',
   /** @internal Set map size. Payload: { width, height } */
   MAP_SET_SIZE: 'map:setsize',
   /** @internal Set pixel ratio. Payload: pixelRatio */
   MAP_SET_PIXEL_RATIO: 'map:setpixelratio',
+  /** @internal Fit the map to a bounding box. Payload: [west, south, east, north] */
+  MAP_FIT_TO_BOUNDS: 'map:fittobounds',
+  /** @internal Set the map center and zoom. Payload: { center: [number, number], zoom?: number } */
+  MAP_SET_VIEW: 'map:setview',
 
   // ============================================
   // Map responses (advanced / subscribe)
@@ -101,15 +105,48 @@ export const EVENTS = {
   /** @internal Emitted when map styles are initialized. */
   MAP_INIT_MAP_STYLES: 'map:initmapstyles',
 
-  /** Emitted when the map style changes. Payload: { styleId: string } */
+  /**
+   * Emitted when the map style has finished loading.
+   * Payload: `{ mapStyleId: string }`
+   *
+   * @example
+   * map.on(EVENTS.MAP_STYLE_CHANGE, ({ mapStyleId }) => {
+   *   console.log('Style changed to', mapStyleId)
+   * })
+   */
   MAP_STYLE_CHANGE: 'map:stylechange',
 
-  /** Emitted when the map style has fully loaded. */
+  /** Emitted when the map has fully loaded. */
   MAP_LOADED: 'map:loaded',
 
-  /** Emitted when the map is ready for interaction. Payload: { map } */
+  /**
+   * Emitted when the map is ready for interaction and initial app state is settled.
+   *
+   * Payload:
+   * - `map` — the underlying map instance
+   * - `view` — the map view (ESRI SDK only)
+   * - `crs` — coordinate reference system string (e.g. `'EPSG:4326'`)
+   * - `mapStyleId` — the ID of the active map style (e.g. `'outdoor'`, `'dark'`)
+   * - `mapSize` — the active map size string (e.g. `'small'`, `'medium'`, `'large'`)
+   *
+   * @example
+   * map.on(EVENTS.MAP_READY, ({ map, mapStyleId, mapSize }) => {
+   *   console.log('Map ready, style:', mapStyleId, 'size:', mapSize)
+   * })
+   */
   MAP_READY: 'map:ready',
 
+  /**
+   * Emitted when the map size changes.
+   * Payload: `{ mapSize: string }`
+   *
+   * @example
+   * map.on(EVENTS.MAP_SIZE_CHANGE, ({ mapSize }) => {
+   *   console.log('Map size changed to', mapSize)
+   * })
+   */
+  MAP_SIZE_CHANGE: 'map:sizechange',
+
   /** Emitted once after the map first becomes idle following initial load. */
   MAP_FIRST_IDLE: 'map:firstidle',
 

package/src/config/getInitialOpenPanels.js

@@ -5,9 +5,9 @@ export function getInitialOpenPanels (panelConfig, breakpoint, prevOpenPanels =
     const configPanel = panelConfig[panelId]
     const bpConfig = configPanel[breakpoint]
 
-    const isInitiallyOpen = bpConfig?.initiallyOpen ?? false
+    const isOpen = bpConfig?.open ?? false
 
-    if (isInitiallyOpen) {
+    if (isOpen) {
       // Preserve any props that were already set in state
       openPanels[panelId] = prevOpenPanels[panelId] || { props: {} }
     }

package/src/config/getInitialOpenPanels.test.js

@@ -8,17 +8,17 @@ describe('getInitialOpenPanels', () => {
     expect(getInitialOpenPanels({}, breakpoint)).toEqual({})
   })
 
-  it('includes panels with initiallyOpen = true and no prev state', () => {
+  it('includes panels with open = true and no prev state', () => {
     const config = {
-      PanelA: { desktop: { initiallyOpen: true } }
+      PanelA: { desktop: { open: true } }
     }
     const result = getInitialOpenPanels(config, breakpoint)
     expect(result).toEqual({ PanelA: { props: {} } })
   })
 
-  it('skips panels with initiallyOpen = false', () => {
+  it('skips panels with open = false', () => {
     const config = {
-      PanelA: { desktop: { initiallyOpen: false } }
+      PanelA: { desktop: { open: false } }
     }
     const result = getInitialOpenPanels(config, breakpoint)
     expect(result).toEqual({})
@@ -34,7 +34,7 @@ describe('getInitialOpenPanels', () => {
 
   it('preserves prevOpenPanels state if exists', () => {
     const config = {
-      PanelA: { desktop: { initiallyOpen: true } }
+      PanelA: { desktop: { open: true } }
     }
     const prevOpenPanels = {
       PanelA: { props: { some: 'value' } }
@@ -45,8 +45,8 @@ describe('getInitialOpenPanels', () => {
 
   it('uses empty props object if no prevOpenPanels entry exists', () => {
     const config = {
-      PanelA: { desktop: { initiallyOpen: true } },
-      PanelB: { desktop: { initiallyOpen: true } }
+      PanelA: { desktop: { open: true } },
+      PanelB: { desktop: { open: true } }
     }
     const prevOpenPanels = {
       PanelA: { props: { existing: true } }

package/src/types.js

@@ -16,8 +16,8 @@
  * @property {number} [order]
  * The order the button appears within its slot.
  *
- * @property {boolean} [showLabel]
- * Whether to a show label, if false then a tooltip is generated from the the label.
+ * @property {boolean} [showLabel=true]
+ * Whether to show a label. If false, a tooltip is generated from the label instead. Defaults to true.
  *
  * @property {string} slot
  * The slot that the button should appear in at this breakpoint.
@@ -37,14 +37,19 @@
  *
  * @typedef {Object} PanelBreakpointConfig
  *
- * @property {boolean} [dismissable]
- * Whether panel can be dismissed.
+ * @property {boolean} [dismissible]
+ * Whether panel can be dismissed. When `false` and `open` is `true`, the panel is always visible at this
+ * breakpoint and any associated panel-toggle button is automatically suppressed.
  *
  * @property {boolean} [exclusive]
  * Whether panel is exclusive. An exclusive panel will hide other panels when it is visible.
  *
- * @property {boolean} [initiallyOpen]
- * Whether panel is initially open.
+ * @property {boolean} [open]
+ * Whether the panel is open. When `true` and combined with `dismissible: false`, the panel is always visible at this
+ * breakpoint and will be restored automatically when the breakpoint is entered.
+ *
+ * @property {boolean} [showLabel]
+ * Whether to show the panel heading. Defaults to true. The heading is visually hidden if false.
  *
  * @property {boolean} [modal]
  * Whether panel is modal.
@@ -198,8 +203,8 @@
  * @property {(offset: [number, number]) => void} panBy
  * Pan map by pixel offset [x, y]. Positive x pans right, positive y pans down.
  *
- * @property {(bounds: [number, number, number, number]) => void} fitToBounds
- * Fit map view to the specified bounds [west, south, east, north] or [minX, minY, maxX, maxY] depending on the crs of the map provider.
+ * @property {(bounds: [number, number, number, number] | object) => void} fitToBounds
+ * Fit map view to the specified bounds [west, south, east, north] or [minX, minY, maxX, maxY] depending on the crs, or a GeoJSON Feature, FeatureCollection, or geometry.
  *
  * @property {(padding: { top?: number, bottom?: number, left?: number, right?: number }) => void} setPadding
  * Set map padding as pixel insets from the top, bottom, left and right edges of the map.
@@ -242,6 +247,10 @@
  *
  * @property {() => void} [clearHighlightedLabel]
  * @experimental Clear any highlighted label.
+ *
+ * @property {(geojson: object, panelRect: DOMRect) => boolean} [isGeometryObscured]
+ * Returns true if the geometry's screen bounding box overlaps the given panel element rectangle.
+ * Used internally by useVisibleGeometry to decide whether to pan/zoom when a panel opens.
  */
 
 /**
@@ -366,11 +375,13 @@
  * @property {ComponentType} [render]
  * Render component.
  *
- * @property {boolean} [showLabel]
- * Whether to show the panel heading. The panel heading is visually hidden if false.
- *
  * @property {PanelBreakpointConfig} tablet
  * Tablet breakpoint configuration.
+ *
+ * @property {object} [visibleGeometry]
+ * GeoJSON Feature, FeatureCollection, or geometry to keep visible when this panel opens.
+ * If any part of the geometry's bounding box is obscured by the safe zone after the panel opens,
+ * the map automatically adjusts: Point or MultiPoint geometry routes to setView(), all other types to fitToBounds().
  */
 
 /**

package/src/utils/getValueForStyle.js

@@ -2,7 +2,7 @@
  * Returns the appropriate color for the given mapStyleId.
  * Supports:
  *  - Simple string colors (#fff, rgba(...))
- *  - Object maps of styleId → color
+ *  - Object maps of mapStyleId → color
  *
  * @param {string|object} colors - Color string or style-mapped color object
  * @param {string} mapStyleId - Current style/theme identifier