Prototype Library

Map

esa-map renders an interactive slippy map with markers, or a themed placeholder when the mapping library is absent. In the Angular source it is designed to wrap Leaflet (via @asymmetrik/ngx-leaflet), defaulting to OpenStreetMap tiles — a MapLibre GL backend would satisfy the same API.

Inherited reference import '@esa/ecology/esa-map';

Overview

Non-functional reference. This page documents the production component, which embeds a real mapping engine behind the inputs below. The frame further down is a static, token-styled mock of the map surface and its placeholder state — it does not pan, zoom, or load tiles.

What it wraps

  • Third-party library: Leaflet, mounted through @asymmetrik/ngx-leaflet. The config shape (center, zoom, tileUrl, attribution, scrollWheelZoom) maps directly onto Leaflet map options; MapLibre GL is a drop-in alternative for vector tiles.
  • Graceful fallback: until the engine is installed, the component renders a placeholder (map-pin icon + install hint + marker count) so layouts compile and reserve space without a hard dependency.
  • Tiles: defaults to OpenStreetMap raster tiles (https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png).

API

Inputs

InputTypeDefaultPurpose
configEsaMapConfig{}Map options, merged with ESA_MAP_DEFAULTS.
markersEsaMapMarker[][]Pins to place on the map.
heightstring'400px'Container height.
disabledbooleanfalseDims and blocks interaction.

Outputs

OutputPayload
markerClickEsaMapMarker
mapClick{ lat: number; lng: number }

EsaMapConfig & EsaMapMarker

EsaMapConfig keyTypeDefault
center[lat, lng][39.8283, -98.5795] (center of US)
zoomnumber5
minZoom / maxZoomnumber2 / 18
tileUrlstringOpenStreetMap tile template
attributionstring'© OpenStreetMap contributors'
scrollWheelZoombooleantrue
EsaMapMarker keyTypeNotes
idstringRequired identifier.
position[lat, lng]Required coordinates.
titlestringHover / aria label.
popupstringHTML content for the popup bubble.
iconstringCustom marker icon URL.
draggablebooleanAllow the user to move the pin.

Anatomy & key states

Ready state (engine loaded) — static mock

© OpenStreetMap contributors
Cedar Creek Outfall

Placeholder state (engine not installed) — actual source markup

Map Component

Install leaflet and @asymmetrik/ngx-leaflet to enable interactive maps.

2 marker(s) configured

Disabled state: host receives opacity: 0.5; pointer-events: none.

Tokens

  • Frame: --color-border (1px border), --radius-200 (corner radius), overflow clipped.
  • Placeholder surface: --color-surface-sunken background, --color-text-muted body, --color-text-secondary title.
  • Spacing: --spacing-200 stack gap, --spacing-500 padding.
  • Marker / popup chrome (handoff): derive from --color-primary, --color-accent, --color-surface, --shadow-200, and --radius-200 so pins and popups match the active theme.