From d69dcd010218879b42cff48002f5e55a946b3d70 Mon Sep 17 00:00:00 2001
From: Danny Koppenhagen <Danny.Koppenhagen@deutschebahn.com>
Date: Thu, 14 Sep 2023 21:35:00 +0200
Subject: [PATCH] feat(ol-source-tile-debug): provide new component for
 TileDebug (#251)

closes #250
---
 docs/.vitepress/config.ts                     |  4 ++
 .../sources/tiledebug/index.md                | 72 +++++++++++++++++++
 docs/public/sitemap.xml                       |  5 ++
 src/components/sources/OlSourceTileDebug.vue  | 62 ++++++++++++++++
 src/components/sources/index.ts               |  3 +
 src/demos/ProjectionRegisterDemo.vue          |  3 +
 src/demos/TileDebugDemo.vue                   | 18 +++++
 vite.config.ts                                |  1 +
 8 files changed, 168 insertions(+)
 create mode 100644 docs/componentsguide/sources/tiledebug/index.md
 create mode 100644 src/components/sources/OlSourceTileDebug.vue
 create mode 100644 src/demos/TileDebugDemo.vue

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 93d820be..b79e963b 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -145,6 +145,10 @@ export default defineConfig({
             text: "ol-source-tile-arcgis-rest",
             link: "/componentsguide/sources/arcgisrest/",
           },
+          {
+            text: "ol-source-tile-debug",
+            link: "/componentsguide/sources/tiledebug/",
+          },
           {
             text: "ol-source-tile-json",
             link: "/componentsguide/sources/tilejson/",
diff --git a/docs/componentsguide/sources/tiledebug/index.md b/docs/componentsguide/sources/tiledebug/index.md
new file mode 100644
index 00000000..c1f4684c
--- /dev/null
+++ b/docs/componentsguide/sources/tiledebug/index.md
@@ -0,0 +1,72 @@
+# ol-source-tile-debug
+
+A pseudo tile source, which does not fetch tiles from a server, but renders a grid outline for the tile grid/projection along with the coordinates for each tile.
+See examples/canvas-tiles for an example.
+
+<script setup>
+import TileDebugDemo from "@demos/TileDebugDemo.vue"
+import ProjectionRegisterDemo from "@demos/ProjectionRegisterDemo.vue"
+</script>
+
+<ClientOnly>
+<ProjectionRegisterDemo />
+<hr />
+<TileDebugDemo />
+</ClientOnly>
+
+## Usage
+
+::: code-group
+
+<<< ../../../../src/demos/TileDebugDemo.vue
+
+:::
+
+## Properties
+
+### Props from OpenLayers
+
+Properties are passed-trough from OpenLayers directly.
+Their types and default values can be checked-out [in the official OpenLayers docs](https://openlayers.org/en/latest/apidoc/module-ol_source_TileDebug-TileDebug.html).
+Only some properties deviate caused by reserved keywords from Vue / HTML.
+This deviating props are described in the section below.
+
+### Deviating Properties
+
+None.
+
+## Events
+
+You have access to all Events from the underlying source.
+Check out [the official OpenLayers docs](https://openlayers.org/en/latest/apidoc/module-ol_source_TileDebug-TileDebug.html) to see the available events tht will be fired.
+
+```html
+<ol-source-tile-debug @error="handleEvent" />
+```
+
+## Methods
+
+You have access to all Methods from the underlying source.
+Check out [the official OpenLayers docs](https://openlayers.org/en/latest/apidoc/module-ol_source_TileDebug-TileDebug.html) to see the available methods.
+
+To access the source, you can use a `ref()` as shown below:
+
+```vue
+<template>
+  <!-- ... -->
+  <ol-source-tile-debug ref="sourceRef" />
+  <!-- ... -->
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import type TileDebug from "ol/source/TileDebug";
+
+const sourceRef = ref<{ source: TileDebug }>(null);
+
+onMounted(() => {
+  const source: TileDebug = sourceRef.value?.source;
+  // call your method on `source`
+});
+</script>
+```
diff --git a/docs/public/sitemap.xml b/docs/public/sitemap.xml
index 5b7e3888..6e56f6dc 100644
--- a/docs/public/sitemap.xml
+++ b/docs/public/sitemap.xml
@@ -97,6 +97,11 @@
   <lastmod>2023-06-22T22:30:00+00:00</lastmod>
   <priority>0.80</priority>
 </url>
+<url>
+  <loc>https://vue3openlayers.netlify.app/componentsguide/sources/tiledebug/</loc>
+  <lastmod>2023-04-07T20:30:00+00:00</lastmod>
+  <priority>0.80</priority>
+</url>
 <url>
   <loc>https://vue3openlayers.netlify.app/componentsguide/sources/tilejson/</loc>
   <lastmod>2023-03-23T09:30:00+00:00</lastmod>
diff --git a/src/components/sources/OlSourceTileDebug.vue b/src/components/sources/OlSourceTileDebug.vue
new file mode 100644
index 00000000..850f0e85
--- /dev/null
+++ b/src/components/sources/OlSourceTileDebug.vue
@@ -0,0 +1,62 @@
+<template>
+  <div v-if="false"></div>
+</template>
+
+<script setup lang="ts">
+import TileDebug, { type Options } from "ol/source/TileDebug";
+import { inject, onMounted, onUnmounted, watch, type Ref, computed } from "vue";
+import usePropsAsObjectProperties from "@/composables/usePropsAsObjectProperties";
+import type TileLayer from "ol/layer/Tile";
+import { useOpenLayersEvents } from "@/composables/useOpenLayersEvents";
+
+// prevent warnings caused by event pass-through via useOpenLayersEvents composable
+defineOptions({
+  inheritAttrs: false,
+});
+
+const props = withDefaults(defineProps<Options>(), {});
+
+const layer = inject<Ref<TileLayer<TileDebug>> | null>("tileLayer");
+const { properties } = usePropsAsObjectProperties(props);
+
+const source = computed(() => new TileDebug(properties));
+
+useOpenLayersEvents(source, [
+  "change",
+  "error",
+  "propertychange",
+  "tileloadend",
+  "tileloadstart",
+  "tileloaderror",
+]);
+
+const applySource = () => {
+  layer?.value?.setSource(null);
+  layer?.value?.setSource(source.value);
+  layer?.value?.changed();
+};
+watch(properties, () => {
+  applySource();
+});
+
+watch(
+  () => layer?.value,
+  () => {
+    applySource();
+  }
+);
+
+onMounted(() => {
+  layer?.value?.setSource(source.value);
+  layer?.value?.changed();
+});
+
+onUnmounted(() => {
+  layer?.value?.setSource(null);
+});
+
+defineExpose({
+  layer,
+  source,
+});
+</script>
diff --git a/src/components/sources/index.ts b/src/components/sources/index.ts
index e188a94b..307e9285 100644
--- a/src/components/sources/index.ts
+++ b/src/components/sources/index.ts
@@ -7,6 +7,7 @@ import OlSourceOSM from "./OlSourceOSM.vue";
 import OlSourceStamen from "./OlSourceStamen.vue";
 import OlSourceTianDiTu from "./OlSourceTianDiTu.vue";
 import OlSourceTileArcGISRest from "@/components/sources/OlSourceTileArcGISRest.vue";
+import OlSourceTileDebug from "./OlSourceTileDebug.vue";
 import OlSourceTileJSON from "./OlSourceTileJSON.vue";
 import OlSourceTileWMS from "./OlSourceTileWMS.vue";
 import OlSourceVector from "./OlSourceVector.vue";
@@ -24,6 +25,7 @@ function install(app: App) {
   app.component("ol-source-stamen", OlSourceStamen);
   app.component("ol-source-tianditu", OlSourceTianDiTu);
   app.component("ol-source-tile-arcgis-rest", OlSourceTileArcGISRest);
+  app.component("ol-source-tile-debug", OlSourceTileDebug);
   app.component("ol-source-tile-json", OlSourceTileJSON);
   app.component("ol-source-tile-wms", OlSourceTileWMS);
   app.component("ol-source-vector", OlSourceVector);
@@ -45,6 +47,7 @@ export {
   OlSourceStamen,
   OlSourceTianDiTu,
   OlSourceTileArcGISRest,
+  OlSourceTileDebug,
   OlSourceTileJSON,
   OlSourceTileWMS,
   OlSourceVector,
diff --git a/src/demos/ProjectionRegisterDemo.vue b/src/demos/ProjectionRegisterDemo.vue
index 24d78ff8..62e7cf91 100644
--- a/src/demos/ProjectionRegisterDemo.vue
+++ b/src/demos/ProjectionRegisterDemo.vue
@@ -20,6 +20,9 @@
     <ol-tile-layer>
       <ol-source-osm />
     </ol-tile-layer>
+    <ol-tile-layer>
+      <ol-source-tile-debug />
+    </ol-tile-layer>
   </ol-map>
 </template>
 
diff --git a/src/demos/TileDebugDemo.vue b/src/demos/TileDebugDemo.vue
new file mode 100644
index 00000000..6db8fd03
--- /dev/null
+++ b/src/demos/TileDebugDemo.vue
@@ -0,0 +1,18 @@
+<template>
+  <ol-map style="height: 400px">
+    <ol-view ref="view" :center="center" :zoom="zoom" />
+    <ol-tile-layer :opacity="0.3">
+      <ol-source-osm />
+    </ol-tile-layer>
+    <ol-tile-layer>
+      <ol-source-tile-debug />
+    </ol-tile-layer>
+  </ol-map>
+</template>
+
+<script setup>
+import { ref } from "vue";
+
+const center = ref([37.4057, 8.81566]);
+const zoom = ref(4);
+</script>
diff --git a/vite.config.ts b/vite.config.ts
index 36772a88..3bffeb24 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -85,6 +85,7 @@ export default defineConfig({
           "ol/source/ImageWMS": "ImageWMS",
           "ol/source/OSM": "OSM",
           "ol/source/Stamen": "Stamen",
+          "ol/source/TileDebug": "TileDebug",
           "ol/source/WMTS": "WMTSSource",
           "ol/tilegrid/WMTS": "TileGridWMTS",
           "ol/source/TileArcGISRest": "TileArcGISRest",