feat: [#2324] Add FullScreen Target Element Id (#2325)

Closes #2324 

This PR adds an additional optional argument to `ex.Screen.goFullScreen('some-element-id')` to target a specific element for the browser fullscreen API.

Example:

```html
<button id="fullscreen">Go Fullscreen</button>
<div id="container" class="container">
    <div class="ui" style="position: absolute; right: 0">
      <div>Some text</div>
      <button>Click me!</button>
    </div>
    <canvas id="game"></canvas>
</div>
```
```typescript
const game = new ex.Engine({
  ...
  canvasElementId: 'game'
});

var fullscreenButton = document.getElementById('fullscreen') as HTMLButtonElement;
fullscreenButton.addEventListener('click', () => {
  if (game.screen.isFullScreen) {
    game.screen.exitFullScreen();
  } else {
    game.screen.goFullScreen('container');
  }
});
```

CHANGELOG.md

@@ -15,7 +15,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
--
+- Add target element id to `ex.Screen.goFullScreen('some-element-id')` to influence the fullscreen element in the fullscreen browser API.
 
 ### Fixed
 

sandbox/src/game.ts

@@ -94,7 +94,7 @@ fullscreenButton.addEventListener('click', () => {
   if (game.screen.isFullScreen) {
     game.screen.exitFullScreen();
   } else {
-    game.screen.goFullScreen();
+    game.screen.goFullScreen('container');
   }
 });
 game.showDebug(true);

src/engine/Screen.ts

@@ -439,8 +439,17 @@ export class Screen {
   /**
    * Requests to go fullscreen using the browser fullscreen api, requires user interaction to be successful.
    * For example, wire this to a user click handler.
-   */
-  public goFullScreen(): Promise<void> {
+   *
+   * Optionally specify a target element id to go fullscreen, by default the game canvas is used
+   * @param elementId
+   */
+  public goFullScreen(elementId?: string): Promise<void> {
+    if (elementId) {
+      const maybeElement = document.getElementById(elementId);
+      if (maybeElement) {
+        return maybeElement.requestFullscreen();
+      }
+    }
     return this._canvas.requestFullscreen();
   }
 

src/spec/ScreenSpec.ts

@@ -418,6 +418,45 @@ describe('A Screen', () => {
     expect(screen).toBeVector(ex.vec(800, 600));
   });
 
+  it('will go fullscreen with the canvas element by default', () => {
+    const mockCanvas = jasmine.createSpyObj('canvas', ['addEventListener', 'removeEventListener', 'requestFullscreen']);
+    mockCanvas.style = {};
+    const sut = new ex.Screen({
+      canvas: mockCanvas,
+      context,
+      browser,
+      displayMode: ex.DisplayMode.Fixed,
+      viewport: { width: 800, height: 600 }
+    });
+
+    sut.goFullScreen();
+
+    expect(mockCanvas.requestFullscreen).toHaveBeenCalled();
+  });
+
+  it('will go fullscreen given an element id', () => {
+    const container = document.createElement('div');
+    container.id = 'some-id';
+    container.appendChild(canvas);
+    document.body.appendChild(container);
+
+    const sut = new ex.Screen({
+      canvas,
+      context,
+      browser,
+      displayMode: ex.DisplayMode.Fixed,
+      viewport: { width: 800, height: 600 }
+    });
+
+    const fakeElement = jasmine.createSpyObj('element', ['requestFullscreen']);
+    spyOn(document, 'getElementById').and.returnValue(fakeElement);
+
+    sut.goFullScreen('some-id');
+
+    expect(document.getElementById).toHaveBeenCalledWith('some-id');
+    expect(fakeElement.requestFullscreen).toHaveBeenCalled();
+  });
+
   it('can round trip convert coordinates', () => {
     Object.defineProperty(window, 'innerWidth', { writable: true, configurable: true, value: 1300 });
     Object.defineProperty(window, 'innerHeight', { writable: true, configurable: true, value: 800 });