[Map][Docs] Add "extra data" section

Author: Kocal

src/Map/doc/index.rst

@@ -416,10 +416,13 @@ Then, you can use this controller in your template:
 Advanced: Low-level options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-UX Map was designed to be renderer-agnostic, it provides a high-level API to configure the map and its elements.
-However, sometimes you may feel limited by this abstraction and want to configure low-level options.
+UX Map was designed to be renderer-agnostic, it provides a high-level API 
+to configure the map and its elements.
+However, sometimes you may feel limited by this abstraction and you would 
+like to configure low-level options.
 
-Fortunately, it is possible to configure those low-level options by using the UX Map events ``ux:map:*:before-create`` with the custom ``rawOptions`` property:
+Fortunately, it is possible to configure those low-level options by using the
+ UX Map events ``ux:map:*:before-create`` with the custom ``rawOptions`` property:
 
 .. code-block:: javascript
 
@@ -492,6 +495,50 @@ Fortunately, it is possible to configure those low-level options by using the UX
         }
     }
 
+Advanced: Passing extra data from PHP to the Stimulus controller
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For higher customization and extensibility, you can also pass extra data from PHP to the Stimulus controller.
+It may be useful to pass data for a specific marker, e.g. the type of place it represents.
+
+Those extra data are only defined and used by you, UX Map only passes them to the Stimulus controller.
+
+To pass extra data from PHP to the Stimulus controller, you must use the ``extra`` property
+ available for ``Marker``, ``InfoWindow``, ``Polygon`` and ``Polyline`` instances::
+
+    $map->addMarker(new Marker(
+        position: new Point(48.822248, 2.337338),
+        title: 'Paris - Parc Montsouris',
+        extra: [
+            'type' => 'Park',
+            // ...
+        ],
+    ));
+
+JavaScript side, you can access your extra data through the ``event.detail.definition.extra`` object
+available on ``ux:map:*:before-create`` and ``ux:map:*:after-create`` events:
+
+.. code-block:: javascript
+
+    // assets/controllers/mymap_controller.js
+
+    import { Controller } from '@hotwired/stimulus';
+
+    export default class extends Controller {
+
+        // ...
+
+        _onMarkerBeforeCreate(event) {
+            console.log(event.detail.definition.extra); // { type: 'Park', ...}
+        }
+
+        _onMarkerAfterCreate(event) {
+            console.log(event.detail.definition.extra); // { type: 'Park', ...}
+        }
+
+        // ...
+    }
+
 .. _map-live-component:
 
 Usage with Live Components