docs(ol-map): allow to use an existing OlMap instance

closes #366

Author: d-koppenhagen

docs/componentsguide/map/index.md

@@ -8,35 +8,47 @@ component to setup `zoom`, `center`, `projection` and other view related propert
 
 [[toc]]
 
-## Demo
-
-<script setup>
-import ViewDemo from "@demos/ViewDemo.vue"
-</script>
-
-<ClientOnly>
-<ViewDemo />
-</ClientOnly>
-
 ## Setup
 
 <!--@include: ../map.plugin.md-->
 
 ## Usage
 
+<script setup>
+import ViewDemo from "@demos/ViewDemo.vue";
+import ExistingMapDemo from "@demos/ExistingMapDemo.vue";
+</script>
+
 | Plugin Usage | Explicit Import |
 | ------------ | :-------------: |
 | `<ol-map>`   |  `<Map.OlMap>`  |
 
 Example of a simple map.
 See also documentation of `ol-view` component.
 
+<ClientOnly>
+
+<ViewDemo />
+</ClientOnly>
+
 ::: code-group
 
 <<< ../../../src/demos/ViewDemo.vue
 
 :::
 
+### re-use existing map
+
+<ClientOnly>
+<ExistingMapDemo />
+</ClientOnly>
+
+::: code-group
+
+<<< ../../../src/demos/ExistingMapDemo.vue
+
+:::
+
 ## Properties
 
 ### Props from OpenLayers
@@ -48,7 +60,11 @@ This deviating props are described in the section below.
 
 ### Deviating Properties
 
-None.
+#### instance
+
+You can re-use an existing [OpenLayers `Map`](https://openlayers.org/en/latest/apidoc/module-ol_Map-Map.html) instance.
+This is probably useful if your app already includes OpenLayers or some other library which uses OpenLayers and exposes its instance.
+The passed `instance` property must be a valid instance of `ol/Map`.
 
 ## Events
 

src/components/map/OlMap.vue

@@ -5,7 +5,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, provide, onMounted, onUnmounted, watch } from "vue";
+import { onMounted, onUnmounted, provide, ref, watch } from "vue";
 import type { AtPixelOptions } from "ol/Map";
 import Map, { type MapOptions } from "ol/Map";
 import type { FeatureLike } from "ol/Feature";
@@ -15,8 +15,9 @@ import type { Pixel } from "ol/pixel";
 import type { Source } from "ol/source";
 import type { Coordinate } from "ol/coordinate";
 import usePropsAsObjectProperties from "@/composables/usePropsAsObjectProperties";
+import { mergeProperties } from "@/helpers/properties";
 
-const props = defineProps<MapOptions>();
+const props = defineProps<MapOptions & { instance?: Map }>();
 
 const emit = defineEmits([
   "change:layerGroup",
@@ -36,21 +37,37 @@ const emit = defineEmits([
   "rendercomplete",
 ]);
 
-const properties = usePropsAsObjectProperties(props);
+const properties = usePropsAsObjectProperties({
+  ...props,
+  instance: undefined,
+});
 
 const mapRef = ref<string | HTMLElement | undefined>(undefined);
-let map: Map | undefined = new Map(properties);
+let map: Map =
+  props.instance || new Map({ ...properties, instance: undefined });
 
-watch(properties, () => {
-  map?.setProperties(properties);
-});
+watch(
+  properties,
+  () => {
+    const p = props.instance
+      ? mergeProperties(properties, props.instance.getProperties())
+      : properties;
+    map?.setProperties(p);
+  },
+  { immediate: true },
+);
 
 onMounted(() => {
-  map?.setTarget(mapRef.value);
+  // bind the map to the component template if not re-using an existing one passed via prop.
+  if (!props.instance) {
+    map?.setTarget(mapRef.value);
+  }
 });
 
 onUnmounted(() => {
-  map?.setTarget(undefined);
+  if (!props.instance) {
+    map?.setTarget(undefined);
+  }
   map = undefined;
 });
 

src/demos/ExistingMapDemo.vue

@@ -0,0 +1,32 @@
+<template>
+  <div id="map" class="map" tabindex="0" style="height: 400px; width: 100%" />
+  <ol-map v-if="mapInstance" :instance="mapInstance">
+    <ol-zoomslider-control />
+  </ol-map>
+</template>
+
+<script setup lang="ts">
+import Map from "ol/Map";
+import { View } from "ol";
+import TileLayer from "ol/layer/Tile";
+import OSM from "ol/source/OSM";
+import { onMounted, ref } from "vue";
+
+const mapInstance = ref<Map>();
+
+onMounted(() => {
+  mapInstance.value = new Map({
+    layers: [
+      new TileLayer({
+        source: new OSM(),
+      }),
+    ],
+    target: "map",
+    view: new View({
+      center: [40, 40],
+      zoom: 2,
+      projection: "EPSG:4326",
+    }),
+  });
+});
+</script>

src/helpers/__tests__/properties.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { mergeProperties } from "../properties";
+
+describe("mergeProperties", () => {
+  it("should merge properties of two objects", () => {
+    const obj1 = {
+      foo: "hello",
+      bar: "world",
+      baz: undefined,
+    };
+    const obj2 = {
+      foo: undefined,
+      bar: "world2",
+    };
+    expect(mergeProperties(obj1, obj2)).toEqual({
+      foo: "hello",
+      bar: "world2",
+      baz: undefined,
+    });
+  });
+});

src/helpers/properties.ts

@@ -0,0 +1,16 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mergeProperties<T extends Record<string, any>>(
+  existingProperties: T,
+  newProperties: Partial<T>,
+): T {
+  // Iterate over the keys in the new properties object
+  for (const key in newProperties) {
+    if (Object.prototype.hasOwnProperty.call(newProperties, key)) {
+      // Only override if the property in the new object is not undefined
+      if (newProperties[key] !== undefined) {
+        existingProperties[key] = newProperties[key]!;
+      }
+    }
+  }
+  return existingProperties;
+}

tests/__screenshots__/general.test.ts/ol-map-should-render-1.png

@@ -3,8 +3,16 @@ import { test } from "@playwright/test";
 import { MapPage } from "./MapPage";
 
 test.describe("ol-map", () => {
-  test("should render", async ({ page }) => {
-    const map = new MapPage(page);
+  test("should render a new map", async ({ page }) => {
+    const map = new MapPage(page, 0);
+    await map.goto("/componentsguide/map/");
+    await map.waitUntilReady();
+    await map.waitUntilCanvasLoaded();
+    await map.checkCanvasScreenshot();
+  });
+
+  test("should render a re-used existing map", async ({ page }) => {
+    const map = new MapPage(page, 1);
     await map.goto("/componentsguide/map/");
     await map.waitUntilReady();
     await map.waitUntilCanvasLoaded();