npm package: @geolonia/maps-suite
Description: High-level map components built on @geolonia/maps-core
Latest version: 0.0.2

# @geolonia/maps-suite

High-level map components for [Geolonia Maps](https://geolonia.com/). Built on `@geolonia/maps-core`, providing familiar classes like `Map`, `Marker`, `InfoWindow`, and `OverlayView` with a simple, imperative API.

## Install

```bash
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

```typescript
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"` | `Map`, `OverlayView` |
| `"marker"` | `Marker`, `AdvancedMarkerElement`, `MarkerClusterer` |
| `"core"` | `LatLng`, `LatLngBounds`, `MVCObject`, `event` |

### `Map`

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

```typescript
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`

```typescript
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.

```typescript
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`

```typescript
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.

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

### `OverlayView`

Base class for implementing custom overlays.

```typescript
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

```bash
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
```

## License

MIT