From dd44d8016e4bb17425c19dcb13015140cb3db794 Mon Sep 17 00:00:00 2001
From: Olivia Guyot <olivia.guyot@camptocamp.com>
Date: Wed, 18 Sep 2024 11:20:02 +0200
Subject: [PATCH] docs: add doc on interactive maps

---
 docs/.vitepress/config.ts |  4 ++++
 docs/reference/maps.md    | 50 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/reference/maps.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index dafda188d8..b7f751258a 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -99,6 +99,10 @@ function sidebarReference() {
           text: 'Pivot Format',
           link: '/reference/pivot-format',
         },
+        {
+          text: 'Interactive maps',
+          link: '/reference/maps',
+        },
       ],
     },
     {
diff --git a/docs/reference/maps.md b/docs/reference/maps.md
new file mode 100644
index 0000000000..83dce0dc9b
--- /dev/null
+++ b/docs/reference/maps.md
@@ -0,0 +1,50 @@
+---
+outline: deep
+---
+
+# Interactive maps
+
+GeoNetwork-UI relies on the [geospatial-sdk](https://github.com/camptocamp/geospatial-sdk) library to render maps. This library works by taking in a Map Context ([see the model here](https://github.com/camptocamp/geospatial-sdk/blob/main/packages/core/lib/model/map-context.ts)) describing the layers and the view of the map to be shown.
+
+Two components are present in GeoNetwork-UI to render a map using a context.
+
+## `MapContainerComponent`
+
+This component simply takes a map context as input and will render it. Everytime the map context changes, the map is updated accordingly.
+
+This component also offers the following events: `mapClick`, `featuresClicked`, `featuresHovered`.
+
+```ts
+import { MapContainerComponent } from '@geonetwork-ui/ui/map'
+```
+
+```html
+<gn-ui-map-container
+  [context]="mapContext"
+  (featuresClick)="handleFeaturesClicked($event)"
+></gn-ui-map-container>
+```
+
+There are a couple of injection tokens that can be used to specify some map options:
+
+- `BASEMAP_LAYERS`: this allows specifying layers that will be added in the background of the map, regardless of the layers in the context; note that there is always a default background tile layer so that the map shown is never empty; this default background layer can be disabled by setting the `DO_NOT_USE_DEFAULT_BASEMAP` token to `true`
+- `MAP_VIEW_CONSTRAINTS`: this allows specifying `maxZoom` and `maxExtent` options that will be applied regardless of the map context
+
+## `MapStateContainerComponent`
+
+This component is connected to a map state accessible through the `MapFacade` class. This allows changing the context used in the map from anywhere in the application, as well as showing the currently selected feature in the map (if any).
+
+The `LayersPanel` component is an example of how another component can interact with the map through the `MapFacade` class.
+
+```ts
+import {
+  MapStateContainerComponent,
+  MapFacade,
+  LayersPanel,
+} from '@geonetwork-ui/feature/map'
+```
+
+```html
+<gn-ui-map-state-container></gn-ui-map-state-container>
+<gn-ui-layers-panel class="absolute inset-y-0 left-0"></gn-ui-layers-panel>
+```