feat: Create richer Basemap class and deprecate basemap_style arg

[kylebarron]

Change list

• Add basemap parameter to Map. This now manages a class with more information than just the basemap style. In particular, this holds the render mode "interleaved", "overlaid", or "reverse-controlled" that was implemented on the JS side in feat: Support two render modes: Standard/deck.gl-first and MapboxOverlay #921
• Deprecate basemap_style parameter to Map. This is superseded by the style parameter to MaplibreBasemap
• Rename CartoBasemap to CartoStyle
• Add before_id parameter to the core Layer. When passed and the basemap render mode is "interleaved",
• Pass interleaved prop down to MapboxOverlay
• Remove temporary render_mode from feat: Support two render modes: Standard/deck.gl-first and MapboxOverlay #921

Rendering layer interleaved in maplibre layer stack:

TODO:

• Validation for beforeId. If beforeId is passed to a layer, try to resolve the basemap style URL to a dict, and then validate that the string value of beforeId exists in that layer stack. Keep a cache of fetched styles so that you're not fetching them repeatedly.
• Warn if beforeId is set when the basemap style is not "interleaved"?
• (next PR): integration with https://github.com/geopandas/xyzservices (see Basemap refactor #494)
• (possibly future PR): examples of rendering different basemap modes

For #494

[kylebarron]

Improve this docstring

[kylebarron]

todo: improve this docstring

[kylebarron]

Need to add MaplibreBasemap to the docs here

[kylebarron]

todo: in the future, we should figure out a way to refactor some of this code out of the top-level App, because it's pretty ugly having all of this layer model, basemap model, view model, etc, state in the top-level body.

[Copilot]

Pull Request Overview

This PR introduces a richer Basemap class system to replace the simple string-based basemap_style parameter, enabling better control over map rendering modes and basemap configuration.

• Adds new MaplibreBasemap class with configurable rendering modes ("interleaved", "overlaid", "reverse-controlled")
• Deprecates basemap_style parameter in favor of the new basemap parameter
• Adds before_id parameter to layers for controlling render order in interleaved mode

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/renderers/types.ts	Adds OverlayRendererProps type for interleaved rendering support
src/renderers/overlay.tsx	Updates overlay renderer to accept interleaved prop
src/model/initialize.ts	Extracts loadModel helper function for loading widget models
src/model/basemap.ts	Creates new MaplibreBasemapModel class with mode and style properties
src/model/base-layer.ts	Adds beforeId property to base layer for render order control
src/index.tsx	Updates main component to use new basemap system and removes deprecated render_mode
lonboard/types/map.py	Updates type definitions to use new MaplibreBasemap instead of CartoBasemap
lonboard/traits.py	Removes unnecessary sync tag from trait initialization
lonboard/basemap.py	Adds MaplibreBasemap class and renames CartoBasemap to CartoStyle
lonboard/_viz.py	Updates viz function to use new basemap system
lonboard/_map.py	Implements deprecation warnings and migration for basemap_style
lonboard/_layer.py	Adds before_id trait to base layer class
docs/api/basemap.md	Updates documentation to reference CartoStyle instead of CartoBasemap

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[vgeorge]

@kylebarron considering it's possible to pass None to the base map prop, shouldn't the Map component render a blank canvas? Right now it's still displaying the default basemap. Just wondering if that's something we’re addressing in this PR or planning to handle separately.

[kylebarron]

Indeed I was planning to add that in the next PR, but I realized it's actually easier than I thought to add, so I can add it here

[kylebarron]

Well, it "works"

but now the red background I thought was always some sort of deck.gl rendering bug... is clear it's actually the deck.gl canvas background color...

[kylebarron]

It turns out that the line

// globals.css
@tailwind utilities;

was causing the background to be red. And taking that out removes the red background.

I was thinking this was edited in #740, but actually it was added all the way back in #417. Perhaps there was a tailwind update that caused @tailwind utilities to make the background red?

This also removes the red "flash" that I've seen for a long time before maplibregl renders above the red background.

But removing that line is problematic because it breaks sidebar and bbox styling:

There must be another way to fix the red background

[vgeorge]

@kylebarron lets keep in mind to later add test coverage for those new usages.

[kylebarron]

The JS-only end-to-end testing is valuable, but I'd really love to have Python-driven testing of the widgets. We can discuss on #524. Maybe we should test out pytest-ipywidgets (https://solara.dev/documentation/advanced/howto/testing#testing-with-a-browser)