@ndwnu/map 3.0.1 → 3.0.3

package/README.md

@@ -1,372 +1,372 @@
-# @ndwnu/map
-
-A facade pattern library for MapLibre GL that simplifies the management of complex map sources and layers. Built by NDW (Nationaal Dataportaal Wegverkeer) for easier development with MapLibre. It also contains the style json file that contains the NDW Basemap styling.
-
-## 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
-- **NDW Basemap style**: A json file with the NDW basemap
-
-## Installation of @ndwnu/map
-
-```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
-
-## NDW Basemap style
-
-The NDW modular basemap is a single MapLibre style file that lets developers compose the right map for their application by toggling grouped layers on and off. The core idea: separate **context** (the quiet reference map you pan and zoom across) from **relevant** (the bold, thematic overlay that tells the story).
-
-### Context / relevant
-
-- **Context layers** are unobtrusive — light, desaturated colors meant to support, not distract. Basemap, roads, admin boundaries, labels.
-- **Relevant layers** are saturated and bold. They carry the data the user actually came for: accessibility, road safety, parking, your own datasets.
-
-### Composition
-
-Each layer carries a `metadata` block — group, sub-group, type, legend name, description. Metadata doesn't affect rendering, but it lets the app reason about layers at runtime:
-
-```json
-"metadata": {
-  "group": "context-roads",
-  "sub-group": "WKD-parking-areas",
-  "type": "context",
-  "legendName": "Parking areas",
-  "desc": ""
-}
-```
-
-Example of how to use groups / subgroups to display / hide a subset of layers with the @ndwnu/map MapElement structure:
-
-```ts
-export class NdwElement extends ApiElement<MapElementEnum, MapFilter, GrgLegendItem> {
-  constructor(config: GrgMapElementConfig, http: HttpClient) {
-    const layerFilter: NdwLayerFilterFunction = (layer) => {
-      return (
-        layer.metadata.group === 'context-map' ||
-        (layer.metadata.group === 'context-roads' &&
-          layer.metadata['sub-group'] !== 'NWB-hectometersigns' &&
-          layer.metadata.group === 'context-roads' &&
-          layer.metadata['sub-group'] !== 'WKD-parking-areas' &&
-          layer.metadata.group === 'context-roads' &&
-          layer.metadata['sub-group'] !== 'FCD-segments')
-      );
-    };
-    super(
-      config,
-      http,
-      environment.mapStyles.ndw,
-      layerFilter as (layer: LayerSpecification) => boolean,
-    );
-  }
-}
-```
-
-When you don't use the MapElement structure, toggle a whole group with plain JavaScript:
-
-```ts
-function toggleGroupLayers(group: string) {
-  const style = map.getStyle();
-  style.layers.forEach((layer) => {
-    if (layer.metadata?.group === group) {
-      const visibility = map.getLayoutProperty(layer.id, 'visibility') || 'visible';
-      map.setLayoutProperty(layer.id, 'visibility', visibility === 'none' ? 'visible' : 'none');
-    }
-  });
-}
-```
-
-### Include in your project
-
-You can either import the style file via `import` and provide it to MapLibre, or you can use the url on maps.ndw.nu:
-
-https://maps.ndw.nu/styles/ndw-basemap/dev/style.json
-
-TODO when style.json hosting task is done by NLS update URL here. [NLS story](https://dev.azure.com/ndwnu/NLS/_workitems/edit/115149)
-
-## 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.
+# @ndwnu/map
+
+A facade pattern library for MapLibre GL that simplifies the management of complex map sources and layers. Built by NDW (Nationaal Dataportaal Wegverkeer) for easier development with MapLibre. It also contains the style json file that contains the NDW Basemap styling.
+
+## 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
+- **NDW Basemap style**: A json file with the NDW basemap
+
+## Installation of @ndwnu/map
+
+```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
+
+## NDW Basemap style
+
+The NDW modular basemap is a single MapLibre style file that lets developers compose the right map for their application by toggling grouped layers on and off. The core idea: separate **context** (the quiet reference map you pan and zoom across) from **relevant** (the bold, thematic overlay that tells the story).
+
+### Context / relevant
+
+- **Context layers** are unobtrusive — light, desaturated colors meant to support, not distract. Basemap, roads, admin boundaries, labels.
+- **Relevant layers** are saturated and bold. They carry the data the user actually came for: accessibility, road safety, parking, your own datasets.
+
+### Composition
+
+Each layer carries a `metadata` block — group, sub-group, type, legend name, description. Metadata doesn't affect rendering, but it lets the app reason about layers at runtime:
+
+```json
+"metadata": {
+  "group": "context-roads",
+  "sub-group": "WKD-parking-areas",
+  "type": "context",
+  "legendName": "Parking areas",
+  "desc": ""
+}
+```
+
+Example of how to use groups / subgroups to display / hide a subset of layers with the @ndwnu/map MapElement structure:
+
+```ts
+export class NdwElement extends ApiElement<MapElementEnum, MapFilter, GrgLegendItem> {
+  constructor(config: GrgMapElementConfig, http: HttpClient) {
+    const layerFilter: NdwLayerFilterFunction = (layer) => {
+      return (
+        layer.metadata.group === 'context-map' ||
+        (layer.metadata.group === 'context-roads' &&
+          layer.metadata['sub-group'] !== 'NWB-hectometersigns' &&
+          layer.metadata.group === 'context-roads' &&
+          layer.metadata['sub-group'] !== 'WKD-parking-areas' &&
+          layer.metadata.group === 'context-roads' &&
+          layer.metadata['sub-group'] !== 'FCD-segments')
+      );
+    };
+    super(
+      config,
+      http,
+      environment.mapStyles.ndw,
+      layerFilter as (layer: LayerSpecification) => boolean,
+    );
+  }
+}
+```
+
+When you don't use the MapElement structure, toggle a whole group with plain JavaScript:
+
+```ts
+function toggleGroupLayers(group: string) {
+  const style = map.getStyle();
+  style.layers.forEach((layer) => {
+    if (layer.metadata?.group === group) {
+      const visibility = map.getLayoutProperty(layer.id, 'visibility') || 'visible';
+      map.setLayoutProperty(layer.id, 'visibility', visibility === 'none' ? 'visible' : 'none');
+    }
+  });
+}
+```
+
+### Include in your project
+
+You can either import the style file via `import` and provide it to MapLibre, or you can use the url on maps.ndw.nu:
+
+https://maps.ndw.nu/styles/ndw-basemap/dev/style.json
+
+TODO when style.json hosting task is done by NLS update URL here. [NLS story](https://dev.azure.com/ndwnu/NLS/_workitems/edit/115149)
+
+## 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.