@ndwnu/map 0.0.1-beta.1 → 0.0.1-beta.3

package/README.md

@@ -1,7 +1,300 @@
-# map
+# @ndwnu/map
 
-This library was generated with [Nx](https://nx.dev).
+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.
 
-## Running unit tests
+## Overview
 
-Run `nx test map` to execute the unit tests.
+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.

package/fesm2022/ndwnu-map.mjs

@@ -1,6 +1,6 @@
 import { BehaviorSubject, map, Subject, takeUntil } from 'rxjs';
 import * as i0 from '@angular/core';
-import { viewChild, Component, ChangeDetectionStrategy, Injectable } from '@angular/core';
+import { viewChild, input, ChangeDetectionStrategy, Component, Injectable } from '@angular/core';
 import { Map } from 'maplibre-gl';
 
 const BOUNDS_NL = [
@@ -12,6 +12,32 @@ const BOUNDS_AMERSFOORT = [
     [5.446205917577942, 52.21132028216525],
 ];
 
+const DEFAULT_MAP_CONFIG = {
+    center: [5.387827, 52.155172],
+    zoom: 8,
+    maxZoom: 18,
+    minZoom: 6,
+    interactive: true,
+    dragRotate: false,
+    doubleClickZoom: true,
+    scrollZoom: true,
+    boxZoom: true,
+    dragPan: true,
+    keyboard: true,
+    touchZoomRotate: true,
+};
+// Common bounds that users can optionally use
+const COMMON_BOUNDS = {
+    NETHERLANDS: [
+        [3.079667, 50.587611],
+        [7.572028, 53.636667],
+    ],
+    AMERSFOORT: [
+        [5.34458238242172, 52.11623605695118],
+        [5.446205917577942, 52.21132028216525],
+    ],
+};
+
 /**
  * Repository for managing map elements.
  * Provides methods to add, remove, show, hide, and toggle map elements.
@@ -348,6 +374,7 @@ class MapSource {
 
 class MapComponent {
     mapContainer = viewChild.required('mapContainer');
+    config = input({}, ...(ngDevMode ? [{ debugName: "config" }] : []));
     map;
     ngAfterViewInit() {
         this.map = this.#createMap(this.mapContainer().nativeElement);
@@ -368,33 +395,35 @@ class MapComponent {
         this.map?.zoomTo(zoomLevel, options);
     }
     #createMap(container) {
-        const map = new Map({
+        const config = { ...DEFAULT_MAP_CONFIG, ...this.config() };
+        const options = {
             container,
             style: {
                 version: 8,
                 sources: {},
                 layers: [],
             },
-            interactive: true,
-            maxZoom: 18,
-            minZoom: 6,
-            bounds: [
-                [5.34458238242172, 52.11623605695118],
-                [5.446205917577942, 52.21132028216525],
-            ],
-        });
-        // Prevent map rotation
-        map.dragRotate.disable();
+            maxZoom: config.maxZoom,
+            minZoom: config.minZoom,
+            interactive: config.interactive,
+            doubleClickZoom: config.doubleClickZoom,
+            scrollZoom: config.scrollZoom,
+            boxZoom: config.boxZoom,
+            dragPan: config.dragPan,
+            keyboard: config.keyboard,
+            touchZoomRotate: config.touchZoomRotate,
+        };
+        const map = new Map(options);
         return map;
     }
     #initiateMapLoading() {
         this.onLoadMap();
         this.resizeMap();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.0.7", ngImport: i0, type: MapComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "19.0.7", type: MapComponent, isStandalone: true, selector: "ng-component", viewQueries: [{ propertyName: "mapContainer", first: true, predicate: ["mapContainer"], descendants: true, isSignal: true }], ngImport: i0, template: '<div #mapContainer class="map"></div>', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: MapComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "20.2.4", type: MapComponent, isStandalone: true, selector: "ng-component", inputs: { config: { classPropertyName: "config", publicName: "config", isSignal: true, isRequired: false, transformFunction: null } }, viewQueries: [{ propertyName: "mapContainer", first: true, predicate: ["mapContainer"], descendants: true, isSignal: true }], ngImport: i0, template: '<div #mapContainer class="map"></div>', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.7", ngImport: i0, type: MapComponent, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: MapComponent, decorators: [{
             type: Component,
             args: [{
                     standalone: true,
@@ -485,10 +514,10 @@ class MaplibreCursorService {
             console.warn(`Cursor type '${cursor}' is not supported.`);
         }
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.0.7", ngImport: i0, type: MaplibreCursorService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.0.7", ngImport: i0, type: MaplibreCursorService, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: MaplibreCursorService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: MaplibreCursorService, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.7", ngImport: i0, type: MaplibreCursorService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: MaplibreCursorService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -499,5 +528,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.7", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { BOUNDS_AMERSFOORT, BOUNDS_NL, MapComponent, MapElement, MapElementRepository, MapLayer, MapSource, MaplibreCursorService };
+export { BOUNDS_AMERSFOORT, BOUNDS_NL, COMMON_BOUNDS, DEFAULT_MAP_CONFIG, MapComponent, MapElement, MapElementRepository, MapLayer, MapSource, MaplibreCursorService };
 //# sourceMappingURL=ndwnu-map.mjs.map