Style Switcher for Examples

[ianthetechie]

I'm opening this PR as a draft first as it is still incomplete, but want to get feedback on the overall approach before proceeding.

Summary

This PR introduces a wider set of basemaps that will cover most examples.

The MapLibre demo tiles work for some examples, but are not great at showcasing MapLibre's full capabilities. As such, MapLibre GL JS examples currently use tiles from several providers (the vast majority being MapTiler, which whitelists the example traffic). Since MapLibre is a vendor-neutral project and most examples are not specific to any particular provider, it makes sense to be able to switch examples between several options. This will result in greater awareness for MapLibre and better examples, since tile providers are incentivized to improve and update the examples, and link directly to them from their own sites.

Where possible (some examples may justifiably be limited to specific providers), I propose that the Americana stylesheet should be the default where we need a more "full" basemap. Other providers will be listed in alphabetical order (full disclosure: I'm affiliated with Stadia Maps, and the proposed sorting puts us at the bottom of the current list).

My reading of the Americana Tile Usage Policy is that MapLibre usage falls under the acceptable usage policy. Though I think we probably need to reach out as the maplibre.org domain, while (I think) hosted on GitHub pages, seems to use CloudFlare in front.

Technical discussion

Deciding when to display a style switcher

Examples that meet some criteria (at doc generation time) will have a style switcher. Currently, the criteria is "does the example use the OSM Americana style URL, since I'm proposing that as the default. I have updated a handful of examples to illustrate this. The rest of the examples will be addressed one-by-one after we agree on the approach.

An alternative would be to include some metadata at the top of the example (more on that later). I have opened this draft without that, as I think it unnecessarily complicates the majority of examples.

Examples that do not pass the "should we have a switcher" check are displayed as they were before. This allows for examples that are provider-specific or only make sense with a single style.

Style switcher implementation

The style switcher is currently a select box added via a map control. We could devise something that looks a bit nicer perhaps, but I opted for this as it's simple and looks reasonably good. The control is injected into the documentation (iframe component) if the generator determines that the example should have a style switcher. This JavaScript is obviously not included in the copyable sample code; it's localized to the iframe.

Changing the selection map style will update the URL with a query string parameter with a style slug. This parameter will be consulted on page load so that copying a URL will let the recipient see the same style.

Changing the map style will also update the example code! The way this currently works is admittedly a bit hackish, since we have to work with a loaded DOM. I believe the method is sufficiently robust, but am open to alternatives. The only MkDocs-native methods I could think of (generating a bunch of tabs with code fences that are 99% duplicate code) would multiply the size of the examples, and would be difficult if not impossible to sync with the map view.

Customizing the set of displayed styles

The set of available map styles can be overridden per example.

The examples are currently plain HTML files, so in the interest of keeping it that way and localizing overrides, I've opted for parsing a leading HTML comment as a JSON configuration (sort of like YAML frontmatter, but we can't have nice things like that in HTML). The generator removes the parsed comment from the example.

<!--
{
  "availableMapStyles": {
    "mapTilerHybrid": {"name": "MapTiler Hybrid", "styleUrl": "https://api.maptiler.com/maps/hybrid/style.json?key=get_your_own_OpIi9ZULNHzrESv6T2vL"},
    "alidadeSatellite": {"name": "Stadia Maps Alidade Satellite", "styleUrl": "https://tiles.stadiamaps.com/styles/alidade_satellite.json"}
  }
}
-->

This is admittedly hackish, but I believe it's robust enough. We already use similar approaches when parsing JS plugins in the doc from the awesom-maplibre repo. The other idea I've considered so far is putting the overrides directly in generate-docs.ts. This is worse in my opinion, since you would need to look at the generator script to understand how an example behaves. That felt wrong.

Known issues

• Going back after changing styles appears to work. However, more complex history manipulation sequences like going forward again, going back multiple times, etc. seem to have no effect on the map style switcher.
• I haven't updated any example thumbnail images

Screenshots

Before

After

Launch Checklist

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• Briefly describe the changes in this PR.
• Include before/after visuals or gifs if this PR includes visual changes.
• Write tests for all new functionality.
• Add an entry to CHANGELOG.md under the ## main section.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.76%. Comparing base (4d8a0f8) to head (614f1ad).
Report is 19 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4813      +/-   ##
==========================================
- Coverage   87.87%   87.76%   -0.11%     
==========================================
  Files         265      265              
  Lines       37577    37590      +13     
  Branches     2349     2359      +10     
==========================================
- Hits        33020    32991      -29     
- Misses       3518     3561      +43     
+ Partials     1039     1038       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[wipfli]

Thanks for opening this pull request and showcasing how different tile providers could be handled on a technical level, @ianthetechie.

The MapLibre Governing Board is in the middle of drafting a policy for the examples and I suggest to wait for the new policy before changing the current state of the docs website.

Thanks for your patience!