Add fullscreenstart, fullscreenend events to FullscreenControl (#2128)

* Add start, end events to FullscreenControl

These are useful for adjusting map settings or styles depending on
whether the map is in fullscreen or not.

This also may help implement #1487

* Move jsdocs to bottom, remove type and property

* Change test to simulate button clicks

* Move events JSDoc to top

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### ✨ Features and improvements
 - Add `setiClusterOptions` to update cluster properties of the added sources: fixing these issues ([#429](https://github.com/maplibre/maplibre-gl-js/issues/429)) and ([1384](https://github.com/maplibre/maplibre-gl-js/issues/1384))
 - Add types for `workerOptions` and `_options` in `geojson_source.ts`
+- Add fullscreenstart, fullscreenend events to FullscreenControl
 - *...Add new stuff here...*
 ### 🐞 Bug fixes
 - *...Add new stuff here...*

src/ui/control/fullscreen_control.test.ts

@@ -53,4 +53,28 @@ describe('FullscreenControl', () => {
         control._onClickFullscreen();
         expect(mapContainer.classList.contains('maplibregl-pseudo-fullscreen')).toBe(false);
     });
+
+    test('start and end events fire for fullscreen button clicks', () => {
+        const map = createMap(undefined, undefined);
+        const fullscreen = new FullscreenControl({});
+
+        const fullscreenstart = jest.fn();
+        const fullscreenend   = jest.fn();
+
+        fullscreen.on('fullscreenstart', fullscreenstart);
+        fullscreen.on('fullscreenend', fullscreenend);
+
+        map.addControl(fullscreen);
+
+        const click = new window.Event('click');
+
+        // Simulate a click to the fullscreen button
+        fullscreen._fullscreenButton.dispatchEvent(click);
+        expect(fullscreenstart).toHaveBeenCalled();
+        expect(fullscreenend).not.toHaveBeenCalled();
+
+        // Second simulated click would exit fullscreen mode
+        fullscreen._fullscreenButton.dispatchEvent(click);
+        expect(fullscreenend).toHaveBeenCalled();
+    });
 });

src/ui/control/fullscreen_control.ts

@@ -2,6 +2,7 @@ import DOM from '../../util/dom';
 
 import {warnOnce} from '../../util/util';
 
+import {Event, Evented} from '../../util/evented';
 import type Map from '../map';
 import type {IControl} from './control';
 
@@ -22,7 +23,23 @@ type FullscreenOptions = {
  * @see [View a fullscreen map](https://maplibre.org/maplibre-gl-js-docs/example/fullscreen/)
  */
 
-class FullscreenControl implements IControl {
+/**
+ * Fired when fullscreen mode has started
+ *
+ * @event fullscreenstart
+ * @memberof FullscreenControl
+ * @instance
+ */
+
+/**
+ * Fired when fullscreen mode has ended
+ *
+ * @event fullscreenend
+ * @memberof FullscreenControl
+ * @instance
+ */
+
+class FullscreenControl extends Evented implements IControl {
     _map: Map;
     _controlContainer: HTMLElement;
     _fullscreen: boolean;
@@ -31,6 +48,7 @@ class FullscreenControl implements IControl {
     _container: HTMLElement;
 
     constructor(options: FullscreenOptions = {}) {
+        super();
         this._fullscreen = false;
 
         if (options && options.container) {
@@ -106,6 +124,12 @@ class FullscreenControl implements IControl {
         this._fullscreenButton.classList.toggle('maplibregl-ctrl-shrink');
         this._fullscreenButton.classList.toggle('maplibregl-ctrl-fullscreen');
         this._updateTitle();
+
+        if (this._fullscreen) {
+            this.fire(new Event('fullscreenstart'));
+        } else {
+            this.fire(new Event('fullscreenend'));
+        }
     }
 
     _onClickFullscreen = () => {
@@ -152,3 +176,4 @@ class FullscreenControl implements IControl {
 }
 
 export default FullscreenControl;
+