@ndwnu/map 2.1.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+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
 
@@ -11,8 +11,9 @@ This library provides a structured approach to managing MapLibre GL maps by intr
 - **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
+## Installation of @ndwnu/map
 
 ```bash
 npm install @ndwnu/map maplibre-gl
@@ -291,6 +292,77 @@ Container for related sources and layers.
 - `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