[Map] Add support for libraries for Google Bridge, inject provider's SDK (L or google) to dispatched events

[Kocal]

Q	A
Bug fix?	no
New feature?	yes
Issues	Fix #...
License	MIT

Follows #2040.

This PR gives the developper access to L (if using Leaflet) or google (if using Google Maps) in dispatched events, so the developper can fully and freely customize the map, their markers (before and after creation), and info windows (before and after creation).

I've added some use cases/examples in respective documentation, but tell me if a better place fits!

Also, please no quick merge this time (even if I like that :D), I really wants some reviews for this PR! cc @javiereguiluz 🙏🏻

Code and screenshots

On my personal project, I have a map with a lot of markers.

Before UX Map, I was using Google Maps because I've found the "glyph" feature really sexy, but I was not able to use it anymore... until now!

With Google Maps

Code:

import {Controller} from "@hotwired/stimulus";

export default class extends Controller
{
    connect() {
        this.element.addEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    disconnect() {
        this.element.removeEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    _onMarkerBeforeCreate(event) {
        const { definition, google } = event.detail;

        const pinElement = new google.maps.marker.PinElement({
            glyph: new URL(String(definition.extra['icon_mask_uri'])), // I've filled `extra` parameter from `new Marker()` (PHP) with the icon mask URL 
            glyphColor: "white",
        });

        definition.rawOptions = {
            content: pinElement.element,
        }
    }
}

Screenshot:

With Leaflet

A dumb example taken from the website:

Code:

import {Controller} from "@hotwired/stimulus";

export default class extends Controller
{
    connect() {
        this.element.addEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    disconnect() {
        this.element.removeEventListener('ux:map:marker:before-create', this._onMarkerBeforeCreate);
    }

    _onMarkerBeforeCreate(event) {
        const { definition, L } = event.detail;
        
        const redIcon = L.icon({
            iconUrl: 'https://leafletjs.com/examples/custom-icons/leaf-red.png',
            shadowUrl: 'https://leafletjs.com/examples/custom-icons/leaf-shadow.png',
            iconSize:     [38, 95], // size of the icon
            shadowSize:   [50, 64], // size of the shadow
            iconAnchor:   [22, 94], // point of the icon which will correspond to marker's location
            shadowAnchor: [4, 62],  // the same for the shadow
            popupAnchor:  [-3, -76] // point from which the popup should open relative to the iconAnchor
        })
        
        definition.rawOptions = {
            icon: redIcon,
        }
    }
}

Screenshot:

[Kocal]

@simondaigre I didn't forget about you #1937 (comment) ;)

[Kocal]

I've updated the PR to:

1. not use the deprecated function loader.load(), instead I've used loader.importLibrary() but it requires to re-built the google.maps object structure ourselves (e.g.: you expect PinElement to be accessed from google.maps.marker.PinElement, not from google.maps.PinElement)
2. to reduce the number of function calls (this.augmentEventPayload()) when events are dispatched N times (N = preconnect + connect + 2 * markers + 2 * infoWindows). Using a protected property looks much more efficient.

[smnandre]

Could you add some shared alias for google and L ? Any better idea than provider or service ?

[smnandre]

Should that be in controller.json or something like that ?

[Kocal]

What do you mean?

[smnandre]

This is new: ux:map:marker:before-create ?

Or did i left way too long to remember ? (4 days hahaha)

[Kocal]

Always has been here ;)

[smnandre]

I think we should illustrate this example with a controller "value"

[smnandre]

This will update all maps on the page (if multiple ones) right ?

[Kocal]

Nope, only the ones using my-map as data-controller

[smnandre]

Oh please remind me to give you a more optimized icon @Kocal ... sorry 😞

[Kocal]

I recently updated it in #2036, I think we are really fine now

[smnandre]

I know this is some "last minute before release" PR, but let's try to not mix features (extra info, librairies configuration) and documentation (custom marker) for the next ones ;)

That beeing said: thanks for the job again @Kocal !! Amazing

[Kocal]

but let's try to not mix features (extra info, librairies configuration) and documentation (custom marker) for the next ones ;)

I'm curious, how would you have done it? Dedicated PRs for:

• Google Maps librairies configuration
• loader.load() rework
• abstracting dispatchEvent
• L and google injection

👀

[kbond]

Thanks Hugo.