refactor(ol-source-stadia-maps): replace old ol-stamen component

BREAKING CHANGE:
The new component `ol-source-stadia-maps` replaced the old `ol-source-stamen` component. Please checkout the official [OpenLayers 8 release notes](https://github.com/openlayers/openlayers/blob/v8.0.0/changelog/upgrade-notes.md#new-stadiamaps-source-replaces-the-stamen-source) for further information.

Author: d-koppenhagen

CHANGELOG.md

@@ -49,7 +49,7 @@ Properties are mostly reflected 1:1 from OpenLayers as Component Properties for
 - 👩🏻‍🔧 migrated all components to use [`<script setup>` syntax](https://vuejs.org/api/sfc-script-setup.html)
 - 🗺️ aligned API with [OpenLayers 7.4.0](https://github.com/openlayers/openlayers/releases/tag/v7.4.0)
 - 📘 updated & restructured the whole documentation
-- 🧩 added new components: `ol-layer-group`, `ol-source-tile-json`, `ol-source-stamen` and `ol-vector-image-layer`
+- 🧩 added new components: `ol-layer-group`, `ol-source-tile-json`, `ol-source-stadia-maps` and `ol-vector-image-layer`
 - 🚀 expose all interactions to be able to call access them via `ref` in templates
 - 🐞 lot's of bug fixes
 - 📖 improved the documentation

docs/.vitepress/config.ts

@@ -134,8 +134,8 @@ export default defineConfig({
             link: "/componentsguide/sources/osm/",
           },
           {
-            text: "ol-source-stamen",
-            link: "/componentsguide/sources/stamen/",
+            text: "ol-source-stadia-maps",
+            link: "/componentsguide/sources/stadiamaps/",
           },
           {
             text: "ol-source-tianditu",

docs/componentsguide/sources/stamen/index.md renamed to docs/componentsguide/sources/stadiamaps/index.md

@@ -1,20 +1,20 @@
-# ol-source-stamen
+# ol-source-stadia-maps
 
-> Layer source for the Stamen tile server.
+> Layer source for the StadiaMaps tile server.
 
 <script setup>
-import StamenDemo from "@demos/StamenDemo.vue"
+import StadiaMapsDemo from "@demos/StadiaMapsDemo.vue"
 </script>
 
 <ClientOnly>
-<StamenDemo />
+<StadiaMapsDemo />
 </ClientOnly>
 
 ## Usage
 
 ::: code-group
 
-<<< ../../../../src/demos/StamenDemo.vue
+<<< ../../../../src/demos/StadiaMapsDemo.vue
 
 :::
 
@@ -23,7 +23,7 @@ import StamenDemo from "@demos/StamenDemo.vue"
 ### 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_Stamen-Stamen.html).
+Their types and default values can be checked-out [in the official OpenLayers docs](https://openlayers.org/en/latest/apidoc/module-ol_source_StadiaMaps-StadiaMaps.html).
 Only some properties deviate caused by reserved keywords from Vue / HTML.
 This deviating props are described in the section below.
 
@@ -34,34 +34,34 @@ 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_Stamen-Stamen.html) to see the available events tht will be fired.
+Check out [the official OpenLayers docs](https://openlayers.org/en/latest/apidoc/module-ol_source_StadiaMaps-StadiaMaps.html) to see the available events tht will be fired.
 
 ```html
-<ol-source-stamen layer="watercolor" @error="handleEvent" />
+<ol-source-stadia-maps layer="stamen_watercolor" @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_Stamen-Stamen.html) to see the available methods.
+Check out [the official OpenLayers docs](https://openlayers.org/en/latest/apidoc/module-ol_source_StadiaMaps-StadiaMaps.html) to see the available methods.
 
 To access the source, you can use a `ref()` as shown below:
 
 ```vue
 <template>
   <!-- ... -->
-  <ol-source-stamen layer="watercolor" ref="sourceRef" />
+  <ol-source-stadia-maps layer="stamen_watercolor" ref="sourceRef" />
   <!-- ... -->
 </template>
 
 <script setup lang="ts">
 import { ref, onMounted } from "vue";
-import type Stamen from "ol/source/Stamen";
+import type StadiaMaps from "ol/source/StadiaMaps";
 
-const sourceRef = ref<{ source: Stamen }>(null);
+const sourceRef = ref<{ source: StadiaMaps }>(null);
 
 onMounted(() => {
-  const source: Stamen = sourceRef.value?.source;
+  const source: StadiaMaps = sourceRef.value?.source;
   // call your method on `source`
 });
 </script>

docs/public/sitemap.xml

@@ -88,7 +88,7 @@
   <priority>0.80</priority>
 </url>
 <url>
-  <loc>https://vue3openlayers.netlify.app/componentsguide/sources/stamen/</loc>
+  <loc>https://vue3openlayers.netlify.app/componentsguide/sources/stadiamaps/</loc>
   <lastmod>2023-06-22T22:30:00+00:00</lastmod>
   <priority>0.80</priority>
 </url>

src/components/sources/OlSourceStamen.vue renamed to src/components/sources/OlSourceStadiaMaps.vue

@@ -3,7 +3,7 @@
 </template>
 
 <script setup lang="ts">
-import Stamen, { type Options } from "ol/source/Stamen";
+import StadiaMaps, { type Options } from "ol/source/StadiaMaps";
 import { inject, onMounted, onUnmounted, watch, type Ref, computed } from "vue";
 import usePropsAsObjectProperties from "@/composables/usePropsAsObjectProperties";
 import type TileLayer from "ol/layer/Tile";
@@ -27,10 +27,12 @@ const props = withDefaults(defineProps<Options>(), {
   wrapX: true,
 });
 
-const layer = inject<Ref<TileLayer<Stamen>> | null>("tileLayer");
+// NOTE: Layers from Stadia Maps do not require an API key for localhost development or most production
+// web deployments. See https://docs.stadiamaps.com/authentication/ for details.
+const layer = inject<Ref<TileLayer<StadiaMaps>> | null>("tileLayer");
 const { properties } = usePropsAsObjectProperties(props);
 
-const source = computed(() => new Stamen(properties));
+const source = computed(() => new StadiaMaps(properties));
 
 useOpenLayersEvents(source, [
   ...TILE_SOURCE_EVENTS,

src/components/sources/index.ts

@@ -4,7 +4,7 @@ import OlSourceCluster from "./OlSourceCluster.vue";
 import OlSourceImageStatic from "./OlSourceImageStatic.vue";
 import OlSourceImageWMS from "./OlSourceImageWMS.vue";
 import OlSourceOSM from "./OlSourceOSM.vue";
-import OlSourceStamen from "./OlSourceStamen.vue";
+import OlSourceStadiaMaps from "./OlSourceStadiaMaps.vue";
 import OlSourceTianDiTu from "./OlSourceTianDiTu.vue";
 import OlSourceTileArcGISRest from "@/components/sources/OlSourceTileArcGISRest.vue";
 import OlSourceTileJSON from "./OlSourceTileJSON.vue";
@@ -26,7 +26,7 @@ function install(app: App) {
   app.component("ol-source-image-static", OlSourceImageStatic);
   app.component("ol-source-image-wms", OlSourceImageWMS);
   app.component("ol-source-osm", OlSourceOSM);
-  app.component("ol-source-stamen", OlSourceStamen);
+  app.component("ol-source-stadia-maps", OlSourceStadiaMaps);
   app.component("ol-source-tianditu", OlSourceTianDiTu);
   app.component("ol-source-tile-arcgis-rest", OlSourceTileArcGISRest);
   app.component("ol-source-tile-json", OlSourceTileJSON);
@@ -47,7 +47,7 @@ export {
   OlSourceImageStatic,
   OlSourceImageWMS,
   OlSourceOSM,
-  OlSourceStamen,
+  OlSourceStadiaMaps,
   OlSourceTianDiTu,
   OlSourceTileArcGISRest,
   OlSourceTileJSON,

src/demos/StamenDemo.vue renamed to src/demos/StadiaMapsDemo.vue

@@ -6,10 +6,10 @@
   >
     <ol-view ref="view" :center="center" :zoom="zoom" />
     <ol-tile-layer>
-      <ol-source-stamen layer="watercolor" />
+      <ol-source-stadia-maps layer="stamen_watercolor" />
     </ol-tile-layer>
     <ol-tile-layer>
-      <ol-source-stamen layer="terrain-labels" />
+      <ol-source-stadia-maps layer="stamen_terrain_labels" />
     </ol-tile-layer>
   </ol-map>
 </template>

vite.config.ts

@@ -84,7 +84,7 @@ export default defineConfig({
           "ol/proj": "proj",
           "ol/source/ImageWMS": "ImageWMS",
           "ol/source/OSM": "OSM",
-          "ol/source/Stamen": "Stamen",
+          "ol/source/StadiaMaps": "StadiaMaps",
           "ol/source/WMTS": "WMTSSource",
           "ol/tilegrid/WMTS": "TileGridWMTS",
           "ol/source/TileArcGISRest": "TileArcGISRest",