Update basemaps docs (#41)

* update basemaps package version to 3.0.1

* flesh out basemap styles page

* options to load basemap styles for maplibre: cdn, npm, json

* prettier

* fix links

.vitepress/config.mts

@@ -63,7 +63,7 @@ export default defineConfig({
         items: [
           { text: "Downloads", link: "/basemaps/downloads" },
           { text: "Basemap Layers", link: "/basemaps/layers" },
-          { text: "Basemap Styles", link: "/basemaps/styles" },
+          { text: "Basemap Themes", link: "/basemaps/themes" },
           { text: "MapLibre GL", link: "/basemaps/maplibre" },
           { text: "Leaflet", link: "/basemaps/leaflet" },
           { text: "OpenLayers", link: "/basemaps/openlayers" },

basemaps/maplibre.md

@@ -5,20 +5,58 @@ outline: deep
 
 # Basemaps for MapLibre
 
+## Assets
 
-The `protomaps-themes-base` NPM module contains basemap layer definitions compatible with OpenStreetMap downloads from Protomaps.
+To render a full basemap, you'll need not only a style and a tileset, but also MapLibre [fontstack](https://maplibre.org/maplibre-style-spec/glyphs/) and [spritesheet](https://maplibre.org/maplibre-style-spec/sprite/) assets.
+
+The assets referenced by the `glyphs` and `sprite` style properties can be downloaded as ZIP files at the [basemaps-assets](http://github.com/protomaps/basemaps-assets) repository, if you need to host them yourself or offline.
+
+### Fonts
+
+The `glyphs` key references a URL hosting pre-compiled fontstacks, required for displaying text labels in MapLibre. Fontstacks can be created with the [font-maker](https://github.com/maplibre/font-maker) tool.
+
+```js
+glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf'
+```
+
+When a style layer defines a `text-font` like `Noto Sans Regular`, this will create requests for a URL like `https://protomaps.github.io/basemaps-assets/fonts/Noto%20Sans%20Regular/0-255.pbf`.
+
+
+You can view a list of available fonts [in the GitHub repository](https://github.com/protomaps/basemaps-assets/tree/main/fonts).
+
+### Sprites
+
+The `sprite` key references a URL specific to one of [the default themes](/basemaps/themes):
+
+```js
+sprite: "https://protomaps.github.io/basemaps-assets/sprites/v3/light"
+```
+
+These are required for townspots, highway shields and point of interest icons.
+
+## Loading styles as JSON
+
+Because [MapLibre styles](https://maplibre.org/maplibre-style-spec/) are JSON documents, the simplest way to define a style in your application is with static JSON. You can use the `Get style JSON` feature of [maps.protomaps.com](maps.protomaps.com) to generate static JSON for a specific theme and style package version.
+
+## Creating styles programatically
+
+For more control and less code, you can add use the [`protomaps-themes-base`](https://www.npmjs.com/package/protomaps-themes-base) NPM package as a dependency.
+
+### Using the npm package
 
 ```bash
 npm install protomaps-themes-base
 ```
+
 ```js
 import layers from 'protomaps-themes-base';
 ```
 
 ```js
 style: {
-    version:8,
+    version: 8,
     glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf',
+    sprite: "https://protomaps.github.io/basemaps-assets/sprites/v3/light",
     sources: {
         "protomaps": {
             type: "vector",
@@ -33,15 +71,18 @@ style: {
 
 the default export from `protomaps-themes-base` is a function that takes 2 arguments:
 
-* the source name of the basemap.
+* the source name of the basemap, like `protomaps` in the `sources` example above.
 
-* the theme, one of `light`, `dark`, `white`, `black`, `grayscale` or `debug`.
+* the [theme](/basemaps/themes), one of `light`, `dark`, `white`, `black`, `grayscale`.
 
-## Fonts
+### Using a CDN
 
-The fonts referenced by the `glyphs` style key can be downloaded as a ZIP at the [basemaps-assets](http://github.com/protomaps/basemaps-assets) GitHub repository.
+Loading the `protomaps-themes-base` package from NPM will define the `protomaps_themes_base` global variable.
 
-Valid font names are: `Noto Sans Regular`, `Noto Sans Medium`, `Noto Sans Italic`
-
-Prior to version 2.0.0-alpha.3, the Glyphs URL was `https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf`.
+```html
+<script src="https://unpkg.com/protomaps-themes-base@3/dist/protomaps-themes-base.js" crossorigin="anonymous"></script>
+```
 
+```js
+layers: protomaps_themes_base.default("protomaps","light")
+````

basemaps/themes.md

@@ -0,0 +1,44 @@
+---
+title: Basemap Themes
+outline: deep
+---
+
+<script setup>
+  import MaplibreMap from '../components/MaplibreMap.vue'
+</script>
+
+# Basemap Themes
+
+These examples use the preferred [MapLibre GL JS](/basemaps/maplibre) library.
+
+## Default Styles
+
+### light
+
+A general-purpose basemap style.
+
+<MaplibreMap theme="light"/>
+
+### dark
+
+A general-purpose basemap style.
+
+<MaplibreMap theme="dark"/>
+
+### white
+
+A style for data visualization.
+
+<MaplibreMap theme="white"/>
+
+### grayscale
+
+A style for data visualization.
+
+<MaplibreMap theme="grayscale"/>
+
+### black
+
+A style for data visualization.
+
+<MaplibreMap theme="black"/>

components/MaplibreMap.vue

@@ -9,10 +9,13 @@ const { isDark } = useData();
 const mapRef = ref(null);
 var map;
 
-const style = () => {
+const style = (passedTheme: string) => {
+  const theme = passedTheme || (isDark.value ? "dark" : "light");
   return {
     version: 8,
-    glyphs: "https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf",
+    glyphs:
+      "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf",
+    sprite: `https://protomaps.github.io/basemaps-assets/sprites/v3/${theme}`,
     sources: {
       protomaps: {
         type: "vector",
@@ -25,14 +28,18 @@ const style = () => {
     transition: {
       duration: 0,
     },
-    layers: layers("protomaps", isDark.value ? "dark" : "light"),
+    layers: layers("protomaps", theme),
   };
 };
 
+const props = defineProps<{
+  theme: string;
+}>();
+
 onMounted(() => {
   map = new maplibregl.Map({
     container: mapRef.value,
-    style: style(),
+    style: style(props.theme),
     cooperativeGestures: true,
   });
 });

guide/getting-started.md

@@ -59,5 +59,5 @@ pmtiles extract https://build.protomaps.com/{{ dateNoDashes }}.pmtiles my_area.p
 ## Next Steps
 
 * Upload your tiles to cloud storage: [Cloud Storage](/pmtiles/cloud-storage)
-* Change the appearance or theme of the basemap: [Basemap Styles](/basemaps/styles)
+* Change the appearance or theme of the basemap: [Basemap Styles](/basemaps/themes)
 * Bring your own datasets: [Creating PMTiles](/pmtiles/create)

package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "maplibre-gl": "^3.4.1",
     "pmtiles": "^2.10.0",
-    "protomaps-themes-base": "^2.0.0-alpha.0",
+    "protomaps-themes-base": "3.0.1",
     "vitepress": "^1.0.0-rc.15"
   },
   "devDependencies": {