feat(TileLayer): Add visibleMinZoom & visibleMaxZoom props

[felixpalmer]

Background

The extent prop in TileLayer controls whether tiles are fetched & drawn when the viewport zoom is below minZoom, but there is no mechanism to control this for zooms above maxZoom. It is also a common source of confusion on whether these props control the levels at which data is loaded or shown.

New API

Two new props are added:

• visibleMinZoom: The zoom below which TileLayer will not draw
• visibleMaxZoom: The zoom above which TileLayer will not draw

To illustrate the interplay between all these props, the website TileLayer example is updated. SEE LIVE DEMO

Change List

• Add visibleMinZoom & visibleMaxZoom props
• Update website example to demonstrate how these props interact
• New widget in website example to explain relation between tile loading & resolving viewport zoom to tile zoom
• Docs

[felixpalmer]

Good name? overzoom?

[coveralls]

coverage: 80.393%. remained the same
when pulling 3274c87 on felix/tile-layer-overdraw
into e096e80 on master.

[Pessimistress]

It has always been a point of confusion because minZoom and maxZoom sounds symmetrical, but they work differently. There are two behaviors - visibility and fetching - that the users may want to control in underzoom/overzoom. I personally think we should have four props for each of these.

[felixpalmer]

@Pessimistress so would you be in favour of:

• minZoom: min zoom level at which tiles are fetched
• maxZoom: max zoom level at which tiles are fetched
• minDisplay: min zoom level at which tiles are displayed
• maxDisplay: max zoom level at which tiles are displayed
• extent: clipping region for tile fetches

minDisplay & maxDisplay are new, while the other keep the current behavior. We then don't need overdraw at all

[chrisgervang]

How about naming the new props:

• visibleMinZoom: min zoom level at which tiles are visible
• visibleMaxZoom: max zoom level at which tiles are visible

Along the same lines as the visible prop for layers and reads naturally ("visible at min zoom")

[ibgreen]

No big objections other as long as we put in some effort on the prop naming, to make this as orthogonal, expandable and intuitive as we can.

FWIW

• I have sometimes wanted a minZoom/maxZoom prop (or visibleMinZoom, visibleMaxZoom or ...) prop on all layers.
• One use case is that as one zooms in one can change between a more aggregated view (perhaps a point layer) and then a detailed layer (e.g. a HexagonLayer) as one gets close, but there are other use cases as well.
• I expect this can be done with the layerFilter mechanism but that is a bit clunky (centralized and non-declarative).

Just mill for the grist if we are ideating about such props.

[chrisgervang]

I could imagine visibleMinZoom / visibleMaxZoom as a base Layer prop. I see it as a configuration of the visible prop, both functionally and in intent.

I also have run into the "refinement" use case you've mentioned @ibgreen. Maplibre has a nice implementation of this.

I'm in favor of starting with the TileLayer and eventually extending it to the base Layer. I think it'd also be nice if visibility toggles could be configured to dissolve - today one can set opacity and a transition prop - how might we extend that to zoom-controlled visibility?

[felixpalmer]

@chrisgervang @ibgreen I've reworked this to use visibleMinZoom / visibleMaxZoom and updated the description. Be sure to check the improved website example

[chrisgervang]

Is it just me or are the tiles not visible between zoom 1 and 3? The configuration gives me the impression that they're supposed to be visible in that range - just not fetching

Great example improvements, btw! I really like the zoom legend

[felixpalmer]

@chrisgervang it's the current behavior - if you don't have extent set, then nothing is drawn below minZoom otherwise you can end up with an explosion in tile requests