@defra/interactive-map 0.0.3-alpha → 0.0.4-alpha

package/src/InteractiveMap/InteractiveMap.js

@@ -1,4 +1,13 @@
 // src/InteractiveMap/InteractiveMap.js
+
+/**
+ * @typedef {import('../types.js').ButtonDefinition} ButtonDefinition
+ * @typedef {import('../types.js').ControlDefinition} ControlDefinition
+ * @typedef {import('../types.js').InteractiveMapConfig} InteractiveMapConfig
+ * @typedef {import('../types.js').MarkerOptions} MarkerOptions
+ * @typedef {import('../types.js').PanelDefinition} PanelDefinition
+ */
+
 import '../scss/main.scss'
 import historyManager from './historyManager.js'
 import { parseDataProperties } from './parseDataProperties.js'
@@ -14,6 +23,10 @@ import { createReverseGeocode } from '../services/reverseGeocode.js'
 import { EVENTS as events } from '../config/events.js'
 import { createEventBus } from '../services/eventBus.js'
 
+/**
+ * Main entry point for the Interactive Map component.
+ * Handles initialization, lifecycle, and public API methods.
+ */
 export default class InteractiveMap {
   _openButton = null
   _root = null // keep react root internally
@@ -21,6 +34,12 @@ export default class InteractiveMap {
   _interfaceDetectorCleanup = null
   _hybridBehaviourCleanup = null
 
+  /**
+   * Create a new InteractiveMap instance.
+   *
+   * @param {string} id - The DOM element ID to mount the map into.
+   * @param {Partial<InteractiveMapConfig>} [props={}] - Configuration options.
+   */
   constructor (id, props = {}) {
     this.id = id
     this.rootEl = document.getElementById(id)
@@ -62,7 +81,6 @@ export default class InteractiveMap {
     })
   }
 
-  // Private methods
   _initialize () {
     if (['buttonFirst', 'hybrid'].includes(this.config.behaviour)) {
       this._openButton = createButton(this.config, this.rootEl, (e) => {
@@ -93,7 +111,12 @@ export default class InteractiveMap {
     history.replaceState(history.state, '', newUrl)
   }
 
-  // Public methods
+  /**
+   * Load and initialize the map application.
+   *
+   * @internal Not intended for end-user use.
+   * @returns {Promise<void>}
+   */
   async loadApp () {
     if (this._openButton) {
       this._openButton.style.display = 'none'
@@ -146,6 +169,11 @@ export default class InteractiveMap {
     }
   }
 
+  /**
+   * Remove the map application and restore the initial state.
+   *
+   * @internal Not intended for end-user use.
+   */
   removeApp () {
     if (this._root && typeof this.unmount === 'function') {
       this.unmount()
@@ -162,6 +190,11 @@ export default class InteractiveMap {
     this.eventBus.emit(events.MAP_DESTROY, { mapId: this.id })
   }
 
+  /**
+   * Destroy the map instance and clean up all resources.
+   *
+   * @internal Not intended for end-user use.
+   */
   destroy () {
     this.removeApp()
     this._breakpointDetector?.destroy()
@@ -171,54 +204,129 @@ export default class InteractiveMap {
     this.eventBus.destroy()
   }
 
-  // API - EventBus methods
+  /**
+   * Subscribe to an event.
+   *
+   * @param {string} event - Event name.
+   * @param {Function} callback - Event handler.
+   */
   on (...args) {
     this.eventBus.on(...args)
   }
 
+  /**
+   * Unsubscribe from an event.
+   *
+   * @param {string} event - Event name.
+   * @param {Function} callback - Event handler to remove.
+   */
   off (...args) {
     this.eventBus.off(...args)
   }
 
+  /**
+   * Emit an event.
+   *
+   * @param {string} event - Event name.
+   * @param {any} [data] - Event data.
+   */
   emit (...args) {
     this.eventBus.emit(...args)
   }
 
-  // API - location markers
+  /**
+   * Add a marker to the map.
+   *
+   * @param {string} id - Unique marker identifier.
+   * @param {[number, number]} coords - Coordinates [lng, lat] or [easting, northing] depending on crs.
+   * @param {MarkerOptions} [options] - Optional marker appearance options.
+   */
   addMarker (id, coords, options) {
     this.eventBus.emit(events.APP_ADD_MARKER, { id, coords, options })
   }
 
+  /**
+   * Remove a marker from the map.
+   *
+   * @param {string} id - Marker identifier to remove.
+   */
   removeMarker (id) {
     this.eventBus.emit(events.APP_REMOVE_MARKER, id)
   }
 
-  // API - change app mode
+  /**
+   * Set the application mode.
+   *
+   * @param {string} mode - Mode identifier.
+   */
   setMode (mode) {
     this.eventBus.emit(events.APP_SET_MODE, mode)
   }
 
-  // Interface API add button/panel/control, remove panel
+  /**
+   * Add a button to the UI.
+   *
+   * @param {string} id - Unique button identifier.
+   * @param {ButtonDefinition} config - Button configuration.
+   */
   addButton (id, config) {
     this.eventBus.emit(events.APP_ADD_BUTTON, { id, config })
   }
 
+  /**
+   * Set or toggle a button state.
+   *
+   * @param {string} id - Button identifier.
+   * @param {'hidden'|'pressed'|'disabled'} prop - The button state to change.
+   * @param {boolean} [value] - Optional boolean. If provided, sets state explicitly; otherwise toggles.
+   */
+  toggleButtonState (id, prop, value) {
+    this.eventBus.emit(events.APP_TOGGLE_BUTTON_STATE, { id, prop, value })
+  }
+
+  /**
+   * Add a panel to the UI.
+   *
+   * @param {string} id - Unique panel identifier.
+   * @param {PanelDefinition} config - Panel configuration.
+   */
   addPanel (id, config) {
     this.eventBus.emit(events.APP_ADD_PANEL, { id, config })
   }
 
+  /**
+   * Remove a panel from the UI.
+   *
+   * @param {string} id - Panel identifier to remove.
+   */
   removePanel (id) {
     this.eventBus.emit(events.APP_REMOVE_PANEL, id)
   }
 
+  /**
+   * Show a panel.
+   *
+   * @param {string} id - Panel identifier to show.
+   */
   showPanel (id) {
     this.eventBus.emit(events.APP_SHOW_PANEL, id)
   }
 
+  /**
+   * Hide a panel.
+   *
+   * @param {string} id - Panel identifier to hide.
+   */
   hidePanel (id) {
     this.eventBus.emit(events.APP_HIDE_PANEL, id)
   }
 
+  /**
+   * Add a custom control to the UI.
+   *
+   * @param {string} id - Unique control identifier.
+   * @param {ControlDefinition} config - Control configuration.
+   */
   addControl (id, config) {
     this.eventBus.emit(events.APP_ADD_CONTROL, { id, config })
   }

package/src/config/defaults.js

@@ -1,32 +1,41 @@
+/**
+ * Default configuration options for InteractiveMap.
+ *
+ * These values are used when no corresponding option is provided by the consumer.
+ * See {@link InteractiveMapConfig} in types.js for full property documentation.
+ *
+ * @type {Partial<import('../types.js').InteractiveMapConfig>}
+ */
 const defaults = {
-  mapViewParamKey: 'mv',
-  behaviour: 'buttonFirst',
-  backgroundColor: 'var(--background-color)',
-  maxMobileWidth: 640,
-  minDesktopWidth: 835,
-  hybridWidth: null, // Defaults to maxMobileWidth if not set
-  containerHeight: '600px',
-  mapSize: 'small',
   appColorScheme: 'light',
   autoColorScheme: false,
-  mapLabel: 'Interactive map',
-  buttonText: 'Map view',
+  backgroundColor: 'var(--background-color)',
+  behaviour: 'buttonFirst',
   buttonClass: 'im-c-open-map-button',
+  buttonText: 'Map view',
+  containerHeight: '600px',
   deviceNotSupportedText: 'Your device is not supported. A map is available with a more up-to-date browser or device.',
+  enableFullscreen: false,
+  enableZoomControls: false,
   genericErrorText: 'There was a problem loading the map. Please try again later.',
+  hasExitButton: false,
+  hybridWidth: null, // Defaults to maxMobileWidth if not set
   keyboardHintText: '<span class="im-u-visually-hidden">Press </span><kbd>Alt</kbd> + <kbd>K</kbd> <span class="im-u-visually-hidden">to view </span>keyboard shortcuts',
-  pageTitle: 'Map view',
-  zoomDelta: 1,
-  nudgeZoomDelta: 0.1,
-  panDelta: 100,
-  nudgePanDelta: 5,
+  mapLabel: 'Interactive map',
   mapProvider: null,
-  reverseGeocode: null,
-  markerShape: 'pin',
+  mapSize: 'small',
+  mapViewParamKey: 'mv',
+  maxMobileWidth: 640,
+  minDesktopWidth: 835,
   markerColor: '#ff0000',
-  enableFullscreen: false,
-  enableZoomControls: false,
-  readMapText: true
+  markerShape: 'pin',
+  nudgePanDelta: 5,
+  nudgeZoomDelta: 0.1,
+  panDelta: 100,
+  pageTitle: 'Map view',
+  readMapText: false,
+  reverseGeocodeProvider: null,
+  zoomDelta: 1
 }
 
 export default defaults

package/src/config/events.js

@@ -1,39 +1,145 @@
+/**
+ * Event constants for the Interactive Map event bus.
+ *
+ * Events are grouped into:
+ * - **App commands**: Internal use, but may be used by plugin authors.
+ * - **App responses**: Subscribe to these with `on()` to react to app state changes.
+ * - **Map commands**: Internal use, but may be used by plugin authors.
+ * - **Map responses**: Subscribe to these with `on()` to react to map state changes.
+ *
+ * @example
+ * // Subscribe to app ready event
+ * map.on(EVENTS.APP_READY, () => {
+ *   console.log('Map is ready!')
+ * })
+ *
+ * // Subscribe to panel events
+ * map.on(EVENTS.APP_PANEL_OPENED, ({ panelId }) => {
+ *   console.log('Panel opened:', panelId)
+ * })
+ */
 export const EVENTS = {
-  // App commands
+  // ============================================
+  // App commands (internal / plugin authors)
+  // ============================================
+
+  /** @internal Add a marker. Payload: { id, coords, options } */
   APP_ADD_MARKER: 'app:addmarker',
+  /** @internal Remove a marker. Payload: id */
   APP_REMOVE_MARKER: 'app:removemarker',
+  /** @internal Set application mode. Payload: mode */
   APP_SET_MODE: 'app:setmode',
+  /** @internal Revert to previous mode. */
   APP_REVERT_MODE: 'app:revertmode',
+  /** @internal Add a button. Payload: { id, config } */
   APP_ADD_BUTTON: 'app:addbutton',
+  /** @internal Set a buttons state. Payload: { id, prop, value? } */
+  APP_TOGGLE_BUTTON_STATE: 'app:togglebuttonstate',
+  /** @internal Add a panel. Payload: { id, config } */
   APP_ADD_PANEL: 'app:addpanel',
+  /** @internal Remove a panel. Payload: id */
   APP_REMOVE_PANEL: 'app:removepanel',
+  /** @internal Show a panel. Payload: id */
   APP_SHOW_PANEL: 'app:showpanel',
+  /** @internal Hide a panel. Payload: id */
   APP_HIDE_PANEL: 'app:hidepanel',
+  /** @internal Add a control. Payload: { id, config } */
   APP_ADD_CONTROL: 'app:addcontrol',
 
-  // App responses
+  // ============================================
+  // App responses (end-user / subscribe)
+  // ============================================
+
+  /**
+   * Emitted when the app is fully initialized and ready for interaction.
+   * Use this to perform actions that require the map to be available.
+   *
+   * @example
+   * map.on(EVENTS.APP_READY, () => {
+   *   map.addMarker('home', [-0.1276, 51.5074])
+   * })
+   */
   APP_READY: 'app:ready',
+
+  /**
+   * Emitted when a panel is opened.
+   * Payload: { panelId: string }
+   *
+   * @example
+   * map.on(EVENTS.APP_PANEL_OPENED, ({ panelId }) => {
+   *   console.log('Panel opened:', panelId)
+   * })
+   */
   APP_PANEL_OPENED: 'app:panelopened',
+
+  /**
+   * Emitted when a panel is closed.
+   * Payload: { panelId: string }
+   *
+   * @example
+   * map.on(EVENTS.APP_PANEL_CLOSED, ({ panelId }) => {
+   *   console.log('Panel closed:', panelId)
+   * })
+   */
   APP_PANEL_CLOSED: 'app:panelclosed',
 
-  // Map commands
+  // ============================================
+  // Map commands (internal / plugin authors)
+  // ============================================
+
+  /** @internal Set map style. Payload: styleId */
   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',
 
-  // Map responses
+  // ============================================
+  // Map responses (advanced / subscribe)
+  // ============================================
+
+  /** @internal Emitted when map styles are initialized. */
   MAP_INIT_MAP_STYLES: 'map:initmapstyles',
+
+  /** Emitted when the map style changes. Payload: { styleId: string } */
   MAP_STYLE_CHANGE: 'map:stylechange',
+
+  /** Emitted when the map style has fully loaded. */
   MAP_LOADED: 'map:loaded',
+
+  /** Emitted when the map is ready for interaction. Payload: { map } */
   MAP_READY: 'map:ready',
+
+  /** Emitted once after the map first becomes idle following initial load. */
   MAP_FIRST_IDLE: 'map:firstidle',
+
+  /** Emitted when map movement starts (pan, zoom, or rotation). */
   MAP_MOVE_START: 'map:movestart',
+
+  /** Emitted continuously during map movement. Payload: { center, zoom, bounds, resolution } */
   MAP_MOVE: 'map:move',
+
+  /** Emitted when map movement ends. Payload: { center, zoom, bounds, resolution } */
   MAP_MOVE_END: 'map:moveend',
+
+  /** Emitted when map state is updated. Payload: { center, zoom, bounds, resolution } */
   MAP_STATE_UPDATED: 'map:stateupdated',
+
+  /** Emitted when map data (tiles, features) changes. */
   MAP_DATA_CHANGE: 'map:datachange',
+
+  /** Emitted on each map render frame. Use sparingly as this fires frequently. */
   MAP_RENDER: 'map:render',
+
+  /**
+   * Emitted when the map is clicked.
+   * Payload: { coords: [number, number], point: { x, y }, features: any[] }
+   */
   MAP_CLICK: 'map:click',
+
+  /** Emitted when the user exits the map (e.g., via the close button). */
   MAP_EXIT: 'map:exit',
+
+  /** Emitted when the map is destroyed. Payload: { mapId: string } */
   MAP_DESTROY: 'map:destroy'
 }

package/src/index.js

@@ -1,3 +1,6 @@
-import InteractiveMap from './InteractiveMap/InteractiveMap.js'
+// Export the main class
+export { default } from './InteractiveMap/InteractiveMap.js'
+export { default as InteractiveMap } from './InteractiveMap/InteractiveMap.js'
 
-export default InteractiveMap
+// Export events
+export { EVENTS } from './config/events.js'

package/src/scss/tools/_border-focus.scss

@@ -136,10 +136,26 @@
 
   // Apply clip-path only to ::before for the shadow
   &::before {
-    $clip-top: if($has-bottom, 0, -20px);
-    $clip-right: if($has-left, 0, -20px);
-    $clip-bottom: if($has-top, 0, -20px);
-    $clip-left: if($has-right, 0, -20px);
+    $clip-top: -20px;
+    $clip-right: -20px;
+    $clip-bottom: -20px;
+    $clip-left: -20px;
+
+    @if $has-bottom {
+      $clip-top: 0;
+    }
+
+    @if $has-left {
+      $clip-right: 0;
+    }
+
+    @if $has-top {
+      $clip-bottom: 0;
+    }
+
+    @if $has-right {
+      $clip-left: 0;
+    }
 
     clip-path: inset(#{$clip-top} #{$clip-right} #{$clip-bottom} #{$clip-left});
   }