@geolonia/maps-suite

High-level map components for Geolonia Maps. Built on @geolonia/maps-core, providing familiar classes like Map, Marker, InfoWindow, and OverlayView with a simple, imperative API.

Install

npm install @geolonia/maps-suite maplibre-gl

maplibre-gl is a peer dependency and must be installed alongside this package. @geolonia/maps-core is included as a dependency.

Usage

import { geolonia } from "@geolonia/maps-suite";

const { Map } = await geolonia.maps.importLibrary("maps");

const map = new geolonia.maps.Map(document.getElementById("map"), {
  center: { lat: 35.6812, lng: 139.7671 },
  zoom: 14,
  apiKey: "YOUR-API-KEY",
});

API

importLibrary(name)

Asynchronously loads a library of classes by name.

| Library | Exports | |---------|---------| | "maps" | MapElement, Map, OverlayView | | "marker" | Marker, AdvancedMarkerElement, MarkerClusterer | | "core" | LatLng, LatLngBounds, MVCObject, event |

MapElement

A custom HTML element <geolonia-map> that initializes a Map instance internally. Supports declarative attributes for initial configuration.

<style>
  geolonia-map {
    display: block;
    width: 100%;
    height: 400px;
  }
</style>
...
<geolonia-map
  center="35.6812,139.7671"
  zoom="14"
  id="my-map"
  map-id="my-map"
  map-style="geolonia/basic-v2"
  api-key="YOUR-API-KEY"
/>

After the element is connected, you can access the internal Map instance via the innerMap property.

const mapElement = document.getElementById("my-map") as geolonia.maps.MapElement;
const map = mapElement.innerMap;

geolonia-maps supports disabling tilt and heading interactions via the tilt-interaction-disabled and heading-interaction-disabled boolean attributes.

Map

The main map class. Internally uses GeoloniaMap from maps-core.

const map = new geolonia.maps.Map(document.getElementById("map"), {
  center: { lat: 35.6812, lng: 139.7671 },
  zoom: 14,
  style: "geolonia/basic-v2",
  apiKey: "YOUR-API-KEY",
});

map.setCenter({ lat: 34.6937, lng: 135.5023 });
map.setZoom(12);
map.fitBounds({ north: 35.7, south: 35.6, east: 139.8, west: 139.7 });

Marker

const marker = new geolonia.maps.Marker({
  position: { lat: 35.6812, lng: 139.7671 },
  map: map,
  title: "Tokyo Station",
  icon: { url: "https://example.com/icon.png" },
});

AdvancedMarkerElement

A marker with custom HTML content.

const content = document.createElement("div");
content.textContent = "📍";

const marker = new geolonia.maps.AdvancedMarkerElement({
  position: { lat: 35.6812, lng: 139.7671 },
  map: map,
  content: content,
});

InfoWindow

const infoWindow = new geolonia.maps.InfoWindow({
  content: "<h3>Tokyo Station</h3><p>Central Tokyo</p>",
});

marker.addListener("click", () => {
  infoWindow.open({ map, anchor: marker });
});

MarkerClusterer

Groups nearby markers into clusters using MapLibre's built-in GeoJSON clustering.

const clusterer = new geolonia.maps.MarkerClusterer({
  map: map,
  markers: [marker1, marker2, marker3],
});

OverlayView

Base class for implementing custom overlays.

class CustomOverlay extends geolonia.maps.OverlayView {
  onAdd() { /* Add DOM elements to panes */ }
  draw() { /* Update position */ }
  onRemove() { /* Remove DOM elements */ }
}

MVCObject

Base class providing property binding and event notification. All components inherit from this class.

Types

| Type | Description | |------|-------------| | LatLng | Represents a latitude/longitude pair | | LatLngBounds | Represents a rectangular geographical bounds | | LatLngLiteral | { lat: number, lng: number } | | LatLngBoundsLiteral | { north, south, east, west } |

Related Packages

| Package | Description | |---------|-------------| | @geolonia/maps-core | Core library extending MapLibre GL JS |

Development

npm install
npm run dev       # Watch build + dev server (http://localhost:3030/e2e/)
npm run build     # Rollup (dev + production)
npm run test      # Vitest unit tests
npm run e2e       # Playwright E2E tests
npm run lint      # Biome
npm run test:coverage # Vitest with coverage report

License

MIT