npm package: @ndwnu/map
Description: A facade pattern library for MapLibre GL that simplifies the management of complex map sources and layers. Built by NDW (Nationaal Dataportaan Wegverkeer) for easier development with MapLibre.
Latest version: 1.0.1

# @ndwnu/map

A facade pattern library for MapLibre GL that simplifies the management of complex map sources and layers. Built by NDW (Nationaal Dataportaan Wegverkeer) for easier development with MapLibre.

## Overview

This library provides a structured approach to managing MapLibre GL maps by introducing the **MapElement** pattern - a container that groups related sources and layers as a single logical unit. MapElements use a generic type (typically an enum) for identification. Instead of managing individual MapLibre sources and layers, you work with MapElements that can be toggled on/off from the UI perspective while handling multiple underlying sources and layers automatically.

## Key Features

- **MapElement Pattern**: Groups multiple sources and layers into logical units
- **Visibility Management**: Easy show/hide functionality for complex map elements
- **Repository Pattern**: Centralized management of all map elements

## Installation

```bash
npm install @ndwnu/map maplibre-gl
```

### CSS Setup

Add MapLibre GL CSS to your `angular.json` styles array:

```json
{
  "styles": ["node_modules/maplibre-gl/dist/maplibre-gl.css"]
}
```

## Development Process

### 1. Create Map Elements

Create a folder structure for your map elements and define an enum for element identification:

```typescript
// map-element.enum.ts
export enum MapElementEnum {
  MyElement = 'my-element',
  AnotherElement = 'another-element',
}
```

```
src/
  map-elements/
    map-element.enum.ts
    my-element/
      my-element.element.ts
      my-element.source.ts
      my-element.layer.ts
```

Example MapElement:

```typescript
import { MapElement, MapElementConfig, MapSource } from '@ndwnu/map';
import { MapElementEnum } from '../map-element.enum';

export class MyElement extends MapElement<MapElementEnum> {
  constructor(config: MapElementConfig<MapElementEnum>) {
    super(config);
    this.sources = [new MyElementSource(config)];
  }
}
```

### 2. Create Element Repository

Extend the MapElementRepository to manage your elements:

```typescript
import { Injectable } from '@angular/core';
import { MapElementRepository } from '@ndwnu/map';
import { Map } from 'maplibre-gl';
import { MapElementEnum } from './map-element.enum';

@Injectable({ providedIn: 'root' })
export class MyMapElementRepository extends MapElementRepository<MapElementEnum> {
  registerMapElements(map: Map) {
    const config = {
      map,
      mapElementRepository: this,
      maplibreCursorService: this.maplibreCursorService,
    };

    [
      new MyElement({ ...config, elementId: MapElementEnum.MyElement, elementOrder: 0 }),
      // Add more elements...
    ].forEach((element) => this.addMapElement(element));
  }
}
```

### 3. Create Map Component

Extend the base MapComponent and optionally provide configuration:

```typescript
import { Component, inject } from '@angular/core';
import { MapComponent, MapConfig } from '@ndwnu/map';
import { MyMapElementRepository } from './map-elements/my-map-element.repository';

@Component({
  selector: 'app-map',
  template: `<div class="map-container"><!-- Map renders here --></div>`,
  styleUrls: ['./map.component.scss'],
})
export class MyMapComponent extends MapComponent {
  readonly #repository = inject(MyMapElementRepository);

  protected onLoadMap() {
    this.#repository.registerMapElements(this.map);
    // Show initial elements
    this.#repository.showMapElement(MapElementEnum.MyElement);
  }

  protected onRemoveMap() {
    this.#repository.removeAllMapElements();
  }

  protected onIdle() {
    // Handle map idle events
  }

  toggleElement(elementId: MapElementEnum) {
    this.#repository.toggleMapElement(elementId);
  }
}
```

### 4. Configure Map (Optional)

You can customize the map behavior by passing a configuration object:

```typescript
// In your parent component template
@Component({
  template: ` <app-map [config]="mapConfig"></app-map> `,
})
export class ParentComponent {
  mapConfig: Partial<MapConfig> = {
    maxZoom: 20,
    minZoom: 8,
    dragRotate: true,
    center: [5.387827, 52.155172],
    zoom: 12,
    scrollZoom: false, // Disable scroll zoom
  };
}
```

Available configuration options:

- `center`: Initial map center position
- `zoom`: Initial zoom level
- `maxZoom`/`minZoom`: Zoom level constraints
- `bounds`: Initial bounds to fit (overrides center/zoom if provided)
- `interactive`: Enable/disable all interactions
- `dragRotate`: Enable/disable rotation via drag
- `doubleClickZoom`: Enable/disable double-click zoom
- `scrollZoom`: Enable/disable scroll wheel zoom
- `boxZoom`: Enable/disable shift+drag box zoom
- `dragPan`: Enable/disable drag to pan
- `keyboard`: Enable/disable keyboard navigation
- `touchZoomRotate`: Enable/disable touch gestures

**Note**: If `bounds` is provided, it will override `center` and `zoom` settings.

You can use predefined bounds:

```typescript
import { COMMON_BOUNDS } from '@ndwnu/map';

mapConfig: Partial<MapConfig> = {
  bounds: COMMON_BOUNDS.NETHERLANDS, // or COMMON_BOUNDS.AMERSFOORT
  maxZoom: 20,
  dragRotate: true,
};
```

### 5. Component Styling

**Important**: Set a height for your map component:

```css
.map-container {
  height: 500px; /* or 100vh for full viewport */
  width: 100%;
}
```

### 6. Register Map Elements

In your `onLoadMap()` method, call `registerMapElements()` to initialize all map elements:

```typescript
protected onLoadMap() {
  this.#repository.registerMapElements(this.map);
  // Set initial visibility
  this.#repository.showMapElement(MapElementEnum.MyElement);
}
```

## Filtering in MapLibre

When working with MapLibre, filters need to be applied to each individual layer, while the filter 'shape' (structure) is tied to the source data. To implement filtering with the current architecture:

1. **Provide filter observables** to your MapElement
2. **Pass filters to sources** during initialization
3. **Apply filters to layers** within each source's layer definitions

Example implementation:

```typescript
// In your MapElement
export class MyElement extends MapElement<MapElementEnum> {
  constructor(
    config: MapElementConfig<MapElementEnum>,
    private filters$: Observable<FilterObject>,
  ) {
    super(config);
    this.sources = [new MyElementSource(config, filters$)];
  }
}

// In your MapSource
export class MyElementSource extends MapSource<MapElementEnum> {
  constructor(
    config: MapElementConfig<MapElementEnum>,
    private filters$: Observable<FilterObject>,
  ) {
    super(config);
    // Subscribe to filter changes and update layers
    this.filters$.subscribe((filters) => this.updateLayerFilters(filters));
  }

  private updateLayerFilters(filters: FilterObject) {
    // Apply filters to each layer in this source
    this.layers.forEach((layer) => {
      layer.applyFilter(filters);
    });
  }
}
```

**Note**: Filter management may be included in future versions of this library to provide a more streamlined filtering experience.

## Example Usage

See the [playground application](../../apps/playground/src/app/pages/map) for a complete implementation example.

## API

### MapComponent (Abstract)

Base component that provides MapLibre integration.

**Methods:**

- `resizeMap()`: Resize the map to fit container
- `zoomToLevel(level: number, options?)`: Zoom to specific level

**Abstract Methods:**

- `onLoadMap()`: Called when map is loaded
- `onRemoveMap()`: Called before map destruction
- `onIdle()`: Called when map becomes idle

### MapElementRepository<T> (Abstract)

Manages collection of map elements.

**Methods:**

- `addMapElement(element)`: Add element to repository
- `removeMapElement(element)`: Remove and destroy element
- `showMapElement(id)`: Make element visible
- `hideMapElement(id)`: Hide element
- `toggleMapElement(id)`: Toggle element visibility

### MapElement<T> (Abstract)

Container for related sources and layers.

**Properties:**

- `id`: Unique identifier
- `elementOrder`: Display order
- `sources`: Array of MapSource instances
- `isVisible`: Current visibility state

## License

MIT

## About NDW

NDW (Nationaal Dataportaan Wegverkeer) - Data from and about road traffic are our core business. We collect, monitor quality, enrich data, store it and make it available.