Basemaps styles v5 (#103)

* Update documentation for @protomaps/basemaps v5.0.0
* rename Theme into Flavor object and add more docs on customization

Author: bdon

.vitepress/config.mts

@@ -75,7 +75,7 @@ export default defineConfig({
         items: [
           { text: "Downloads", link: "/basemaps/downloads" },
           { text: "Basemap Layers", link: "/basemaps/layers" },
-          { text: "Basemap Themes", link: "/basemaps/themes" },
+          { text: "Basemap Flavors", link: "/basemaps/flavors" },
           { text: "Basemap Localization", link: "/basemaps/localization" },
           { text: "Building Tiles", link: "/basemaps/build" },
           { text: "MapLibre GL", link: "/basemaps/maplibre" },

basemaps/downloads.md

@@ -18,7 +18,7 @@ Please note that **URLs may change** and hotlinking to these downloads are disco
 
 ## Current Version
 
-The Version 4 Protomaps basemap daily build channel is available at [maps.protomaps.com/builds](https://maps.protomaps.com/builds). This is compatible with `protomaps-themes-base` style v4.0.0 and newer.
+The Version 4 Protomaps basemap daily build channel is available at [maps.protomaps.com/builds](https://maps.protomaps.com/builds). This is compatible with `@protomaps/basemaps` style v4.0.0 and newer.
 
 [BLAKE3](https://github.com/BLAKE3-team/BLAKE3/releases/) hashes are provided for daily builds. Use `b3sum` to verify the integrity of your downloaded file.
 

basemaps/flavors.md

@@ -0,0 +1,59 @@
+---
+title: Basemap Flavors
+outline: deep
+---
+
+<script setup>
+  import MaplibreMap from '../components/MaplibreMap.vue'
+</script>
+
+# Basemap Flavors
+
+These examples use the preferred [MapLibre GL JS](/basemaps/maplibre) library.
+
+The `Flavor` TypeScript interface is the preferred way to customize the basemap style. See the shape of the interface at the [@protomaps/basemaps TypeScript docs](https://maps.protomaps.com/typedoc/interfaces/Flavor.html).
+
+A `Flavor` is a plain object of color definitions and optional properties such as font names, landcover shades and POI properties. You can define a `Flavor` yourself for a custom style, similar to a text editor color scheme, or use one of the default named flavors as a base.
+
+## Default Flavors
+
+These flavors are included as part of the `@protomaps/basemaps` package.
+
+### light
+
+A general-purpose basemap with icons.
+
+<MaplibreMap flavor="light" :zoom=13 :lat="51.509" :lng="-0.14"/>
+
+### dark
+
+A general-purpose basemap with icons.
+
+<MaplibreMap flavor="dark" :zoom=13 :lat="51.509" :lng="-0.14"/>
+
+### white
+
+A flavor for data visualization.
+
+<MaplibreMap flavor="white" :zoom=13 :lat="51.509" :lng="-0.14"/>
+
+### grayscale
+
+A flavor for data visualization.
+
+<MaplibreMap flavor="grayscale" :zoom=13 :lat="51.509" :lng="-0.14"/>
+
+### black
+
+A flavor for data visualization.
+
+<MaplibreMap flavor="black" :zoom=13 :lat="51.509" :lng="-0.14"/>
+
+## Overriding Defaults
+
+Use [ES6 spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) to override any part of the Flavor object. For example, to color buildings red:
+
+```ts
+import { namedFlavor } from "@protomaps/basemaps"
+let flavor = {...namedFlavor("light"),buildings:"red")
+```

basemaps/maplibre.md

@@ -26,7 +26,7 @@ You can view a list of available fonts [in the GitHub repository](https://github
 
 ### Sprites
 
-The `sprite` key references a URL specific to one of [the default themes](/basemaps/themes):
+The `sprite` key references a URL specific to one of [the default flavors](/basemaps/flavors):
 
 ```js
 sprite: "https://protomaps.github.io/basemaps-assets/sprites/v4/light"
@@ -36,20 +36,20 @@ 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](https://maps.protomaps.com) to generate static JSON for a specific theme and style package version.
+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](https://maps.protomaps.com) to generate static JSON for a specific flavor 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.
+For more control and less code, you can add use the [`@protomaps/basemaps`](https://www.npmjs.com/package/@protomaps/basemaps) NPM package as a dependency.
 
 ### Using the npm package
 
 ```bash
-npm install protomaps-themes-base
+npm install @protomaps/basemaps
 ```
 
 ```js
-import layers from 'protomaps-themes-base';
+import { layers, namedFlavor } from '@protomaps/basemaps';
 ```
 
 ```js
@@ -65,24 +65,26 @@ style: {
             attribution: '<a href="https://protomaps.com">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>'
         }
     },
-    layers: layers("protomaps","light")
+    layers: layers("protomaps",namedFlavor("light"),{lang:"en"})
 }
 ```
 
-the default export from `protomaps-themes-base` is a function that takes 2 arguments:
+the `layers` from `@protomaps/basemaps` is a function that takes 3 arguments:
 
 * the source name of the basemap, like `protomaps` in the `sources` example above.
 
-* the [theme](/basemaps/themes), one of `light`, `dark`, `white`, `black`, `grayscale`.
+* A [flavor object](/basemaps/flavors); the defaults can be fetched `namedFlavor` with `light`, `dark`, `white`, `black`, `grayscale`.
+
+* An options object: to display labels. pass a `lang` key. Pass `labelsOnly` to display only labels.
 
 ### Using a CDN
 
-Loading the `protomaps-themes-base` package from NPM will define the `protomaps_themes_base` global variable.
+Loading the `@protomaps/basemaps` package from NPM will define the `basemaps` global variable.
 
 ```html
-<script src="https://unpkg.com/protomaps-themes-base@4/dist/protomaps-themes-base.js" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@protomaps/basemaps@5/dist/basemaps.js" crossorigin="anonymous"></script>
 ```
 
 ```js
-layers: protomaps_themes_base.default("protomaps","light")
+layers: basemaps.layers("protomaps",basemaps.namedFlavor("light"),{lang:"en"})
 ````

basemaps/themes.md

@@ -1,8 +1,11 @@
 <script setup lang="ts">
 import maplibregl from "maplibre-gl";
 import { ref, onMounted, onUpdated, watch } from "vue";
-import { default as layers } from "protomaps-themes-base";
-import { language_script_pairs } from "protomaps-themes-base";
+import {
+  language_script_pairs,
+  layers,
+  namedFlavor,
+} from "@protomaps/basemaps";
 import { useData } from "vitepress";
 
 const { isDark } = useData();
@@ -67,9 +70,9 @@ const highlightLayers = (sourceName: string, highlightName?: string) => {
   ];
 };
 
-const style = (passedTheme?: string, highlightLayer?: string, lang?: lang) => {
-  const theme =
-    passedTheme ||
+const style = (passedFlavor?: string, highlightLayer?: string, lang?: lang) => {
+  const flavor =
+    passedFlavor ||
     (isDark.value
       ? highlightLayer
         ? "black"
@@ -81,7 +84,7 @@ const style = (passedTheme?: string, highlightLayer?: string, lang?: lang) => {
     version: 8,
     glyphs:
       "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf",
-    sprite: `https://protomaps.github.io/basemaps-assets/sprites/v4/${theme}`,
+    sprite: `https://protomaps.github.io/basemaps-assets/sprites/v4/${flavor}`,
     sources: {
       protomaps: {
         type: "vector",
@@ -91,14 +94,14 @@ const style = (passedTheme?: string, highlightLayer?: string, lang?: lang) => {
     transition: {
       duration: 0,
     },
-    layers: layers("protomaps", theme, lang).concat(
+    layers: layers("protomaps", namedFlavor(flavor), { lang: lang }).concat(
       highlightLayers("protomaps", highlightLayer),
     ),
   };
 };
 
 const props = defineProps<{
-  theme?: string;
+  flavor?: string;
   highlightLayer?: string;
   center?: number;
   zoom?: number;
@@ -118,7 +121,7 @@ onMounted(() => {
   currentZoom.value = props.zoom;
   map = new maplibregl.Map({
     container: mapRef.value,
-    style: style(props.theme, props.highlightLayer),
+    style: style(props.flavor, props.highlightLayer, lang),
     cooperativeGestures: true,
     attributionControl: false,
     center: props.lng && props.lat ? [props.lng, props.lat] : [0, 0],
@@ -157,7 +160,7 @@ onMounted(() => {
 });
 
 watch([isDark, lang], () => {
-  map.setStyle(style(props.theme, props.highlightLayer, lang.value));
+  map.setStyle(style(props.flavor, props.highlightLayer, lang.value));
 });
 
 language_script_pairs.sort((a, b) => a.full_name.localeCompare(b.full_name));

components/MaplibreMap.vue

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

guide/getting-started.md

@@ -93,7 +93,7 @@ Below is a complete example of a map application that avoids third-party data pr
         <link rel="stylesheet" href="maplibre-gl.css">
         <script src="maplibre-gl.js"></script>
         <script src="pmtiles.js"></script>
-        <script src="protomaps-themes-base.js"></script>
+        <script src="basemaps.js"></script>
     </head>
     <body>
         <div id="map" style="height: 100%; width: 100%"></div>
@@ -119,7 +119,7 @@ Below is a complete example of a map application that avoids third-party data pr
                     attribution: '© <a href="https://openstreetmap.org">OpenStreetMap</a>'
                   },
                 },
-                layers: protomaps_themes_base.default("protomaps", "light")
+                layers: basemaps.layers("protomaps", basemaps.namedFlavor("light"), {lang: "en"})
               },
             });
         </script>
@@ -129,7 +129,7 @@ Below is a complete example of a map application that avoids third-party data pr
 
 * `maplibre-gl.js`, `maplibre-gl.css` - JavaScript and CSS for the MapLibre GL rendering library.
 * `pmtiles.js` - JavaScript for decoding PMTiles archives in the browser.
-* `protomaps-themes-base.js` - JavaScript for creating a MapLibre GL style for a basemap tileset. 
+* `basemaps.js` - JavaScript for creating a MapLibre GL style for a basemap tileset. 
 * `mapbox-gl-rtl-text.min.js` - MapLibre plugin for supporting right-to-left languages.
 * `fonts/{fontstack}/{range}.pbf` - Font glyphs for rendering labels, available at [protomaps/basemaps-assets](https://github.com/protomaps/basemaps-assets).
-* `sprites/{version/{theme}` - Sprites for basemap icons, available at [protomaps/basemaps-assets](https://github.com/protomaps/basemaps-assets).
+* `sprites/{version/{flavor_name}` - Sprites for basemap icons, available at [protomaps/basemaps-assets](https://github.com/protomaps/basemaps-assets).

guide/security-privacy.md

@@ -9,7 +9,7 @@
   "dependencies": {
     "maplibre-gl": "^4.7.1",
     "pmtiles": "^4.1.0",
-    "protomaps-themes-base": "4.4.0",
+    "@protomaps/basemaps": "5.0.0",
     "vitepress": "^1.5.0"
   },
   "devDependencies": {