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

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} bbox - Bounds as [west, south, east, north] or [minX, minY, maxX, maxY] depending on the crs, or a GeoJSON Feature, FeatureCollection, or geometry.
+   */
+  fitToBounds (bbox) {
+    this.eventBus.emit(events.MAP_FIT_TO_BOUNDS, bbox)
+  }
+
+  /**
+   * 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.
@@ -366,9 +371,6 @@
  * @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.
  */

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