Layer documentation vs Repo Examples -- Layer documentation's example does not seem to work

Description

Hello,

First I want to say thanks for providing react-map-gl! I am excited to learn how it works and how I can customize it.

Today I noticed two different implementations of a Layer.

The documentation shows a very clear, understandable, simple implementation of a element:

https://visgl.github.io/react-map-gl/docs/api-reference/layer

However, implementing the code as shown there, it does not run unless this change is made:

type: 'fill', --> type: 'fill' as 'fill'

Without this, you get the following error:
"Types of property 'type' are incompatible.
Type 'string' is not assignable to type '"sky"'."

This is a strange error message, as this is not a "sky" layer, nor is "sky" specified anywhere in the example code I am using.

Fixed error, but map does not render due to a error in the browser code:

** Edit ** Oops in the screenshot below, the error is the result of me introducing a small bug-- I accidentally placed not within the element. Once I corrected this, the map is rendering in the browser. (Although I don't see the Layer showing up-- b/c I didn't add a source. I didn't add a source b/c I didn't see it in the Layer API documentation until layer... since its way at the bottom in "options", even though it's a requirement for some layers, more on that below.)

That said, on the right in the code you can see that I added " as 'fill' " because I suspected it needed that particular type info. I'm not sure if it actually does-- the Layer API webpage doesn't show it, so I added it just in case.

I wish the Layer API was a bit more... pasteable-- when I see an example in an API documentation, at least with ReactJS, the idea is typically "you can paste this component and it'll just work" So, personally, as a developer, that's what I love to see.

In this case, the Layer API example doesn't "just work"-- it needs type info, and a source. So... if someone with experience has a good code example out there, perhaps they can update the Layer API webpage to include a 100% working example, of a common use case: a roadmap layer.

One thing I really appreciate about react-map-gl is its documentation, so I wanted to post here to see if the Layer documentation might need someone to QA it, so that it's easy to copy & paste into a project and run, without any errors.

Also, I really like the examples in the visgyl/react-map-gl project. However its implementation of Layer is very different from the documentation-- This example in the examples/layers/src/control-panel.tsx shows a different usage of the Layer element.

It doesn't import (neither here nor its app.tsx file). Also, this usage of Layer is not very understandable to me. I think it's great to show how to customize things, but I think prior to that, it's important to have examples which follow the documentation, as a foundation, prior to going into a custom example.

So, with that, I was hoping someone could help me understand how to use the element in a way similar to what is shown in the documentation.

Thanks!

Update

I see that this Layer example shows additional information which is not shown in the Layer documentation webpage.

https://github.com/visgl/react-map-gl/blob/master/examples/terrain/src/app.tsx

// the Doc page does not show import of a Layer type ("SkyLayer" here-- in my example i'd use "FillLayer")

// Perhaps the doc page needs to show: 
// import type {FillLayer} from 'react-map-gl';

// The doc page might also need to show:
// const parkLayer: FillLayer = {
// in place of "const skyLayer: SkyLayer = {" below

import type {SkyLayer} from 'react-map-gl';

const skyLayer: SkyLayer = {
  id: 'sky',
  type: 'sky',
  paint: {
    'sky-type': 'atmosphere',
    'sky-atmosphere-sun': [0.0, 0.0],
    'sky-atmosphere-sun-intensity': 15
  }
};

Expected Behavior

I thought that by using the Layer element, inside of the Map element, that I would see a system of roads covering the main map.

Steps to Reproduce

1. Clone https://github.com/visgl/react-map-gl
2. For me, I wanted to use the 'draw-polygon' example as a starting point, and then show a layer on top of it, of a road system. The draw-polygon example has no roads or ways to know where the map is-- such as town or city names. So, it's why I want to add a layer there: to understand what location the map is showing
3. Next, I tried to copy & paste the Layer example from documentation: https://visgl.github.io/react-map-gl/docs/api-reference/layer
4. It doesn't work though, for two reasons: A. no Source is included in the Documentation page, so I didn't initially add it. However, I checked the terrain example project, and it has one. I just don't know how to set up a source for a roadmap yet-- I'm sure its not tough, I just need to do more research on that. B. An error about missing a "sky" type in the terminal console-- the Layer isn't a sky layer, so the error message could likely use improvement.

Environment

• Framework version: "@mapbox/mapbox-gl-draw": "^1.3.0",
• Map library: "mapbox-gl": "^2.0.0"
  "@types/mapbox__mapbox-gl-draw": "^1.2.3",
  "@turf/area": "^6.5.0",
• Browser: Chrome
• OS: MacOS Big Sur (11.3)

Code

This code works, but I need a 'vector source' apparently. I really wish the Documentation of the Layer API showed this in its code example.

Although it does mention Source as an "option" down at the bottom.

However, given the browser error below, "Source" doesn't seem optional. The layer API page says: "source is required by some layer types in the Mapbox style specification."

Hmm.. if it's required by some and optional by some, I'd prefer this text be either highlighted, or placed outside of the "options" section. But that's just a personal preference in order to see that important information more visibly, rather than leaving it at the bottom of the doc page/

I do see an example here of using a Source.

Browser error:
map.js:42 Error: layers.landuse_park: layer "landuse_park" requires a vector source

import * as React from 'react';
import {useState, useCallback} from 'react';
import {createRoot} from 'react-dom/client';
import Map, {NavigationControl, Layer} from 'react-map-gl';

import DrawControl from './draw-control';
import ControlPanel from './control-panel';

const TOKEN = '<TOKEN HERE>'; // Set your mapbox token here

// this type import is not shown in the docs: https://visgl.github.io/react-map-gl/docs/api-reference/layer
import type {FillLayer} from 'react-map-gl';

const parkLayer: FillLayer = {
  id: 'landuse_park',
  type: 'fill', 
// Not sure if this should be:
//   type: 'fill' as 'fill',
  source: 'mapbox',
  'source-layer': 'landuse',
  filter: ['==', 'class', 'park'],
  paint: {
    'fill-color': '#4E3FC8'
  }
};

export default function App() {
  const [features, setFeatures] = useState({});

  const onUpdate = useCallback(e => {
    setFeatures(currFeatures => {
      const newFeatures = {...currFeatures};
      console.log('newFeatures', newFeatures)
      for (const f of e.features) {
        newFeatures[f.id] = f;
      }
      return newFeatures;
    });
  }, []);

  const onDelete = useCallback(e => {
    setFeatures(currFeatures => {
      const newFeatures = {...currFeatures};
      for (const f of e.features) {
        delete newFeatures[f.id];
      }
      return newFeatures;
    });
  }, []);

  return (
    <>
      <Map
        initialViewState={{
          longitude: -91.874,
          latitude: 42.76,
          zoom: 12
        }}
        mapStyle="mapbox://styles/mapbox/satellite-v9"
        mapboxAccessToken={TOKEN}
      >
        <DrawControl
          position="top-left"
          displayControlsDefault={false}
          controls={{
            polygon: true,
            trash: true
          }}
          defaultMode="draw_polygon"
          onCreate={onUpdate}
          onUpdate={onUpdate}
          onDelete={onDelete}
        />
        <NavigationControl position='bottom-right' />
        <Layer {...parkLayer} />
      </Map>
      <ControlPanel polygons={Object.values(features)} />
      // Accidentally placed Layer outside of Map element earlier, which caused the browser bug-- as shown here:
      // <Layer {...parkLayer} />
    </>
  );
}

export function renderToDom(container) {
  createRoot(container).render(<App />);
}

Start with docs/api-reference/layer and compare its example with examples/terrain/src/app.tsx and examples/layers/src/control-panel.tsx. Verify the Layer example can be copied into a Map and clarify the required source and TypeScript layer type information. Done means the documentation presents a working, understandable example and explains when source is required.