beforeId behavior when layer is not found

[ricardohsweiss]

mapbox-gl-js version: 3.7.0

Question

As a result of my exploration in the source code, Ive found that when adding a layer and setting the beforeId option if the layer id is not present in the map, mapbox dont add this layer to the map as seem in the following piece of code from the addLayer method implementation:

if (before) {
            const beforeIndex = this._order.indexOf(before);
            if (beforeIndex === -1) {
                this.fire(new ErrorEvent(new Error(`Layer with id "${before}" does not exist on this map.`)));
                return;
            }

            // If the layer we're inserting doesn't have a slot,
            // or it has the same slot as the 'before' layer,
            // then we can insert the new layer before the existing one.
            const beforeLayer = this._layers[before];
            if (layer.slot === beforeLayer.slot) index = beforeIndex;
            else warnOnce(`Layer with id "${before}" has a different slot. Layers can only be rearranged within the same slot.`);
        }

I couldnt find this information in the docs though, if this is the case that the layer is not added to the map if beforeId layer does not exist, can I create a PR to add this information to the docs?

Links to related documentation

https://docs.mapbox.com/mapbox-gl-js/api/map/#map#addlayer