feat: implement spatial navigation

src/css/components/_button.scss

@@ -15,6 +15,12 @@
   appearance:         none;
 }
 
+// Replacement for focus in case spatial navigation is enabled
+.video-js.vjs-spatial-navigation-enabled .vjs-button:focus {
+  outline: 0.0625em solid rgba($primary-foreground-color, 1);
+  box-shadow: none;
+}
+
 .vjs-control .vjs-button {
   width: 100%;
   height: 100%;

src/css/components/_captions-settings.scss

@@ -3,6 +3,11 @@
   background-color: rgba($primary-background-color, 0.75);
   color: $primary-foreground-color;
   height: 70%;
+
+  // When Spatial Navigation is enabled
+  .vjs-spatial-navigation-enabled & {
+    height: 80%;
+  }
 }
 
 // Hide if an error occurs

src/css/components/_control-bar.scss

@@ -10,6 +10,10 @@
   @include background-color-with-alpha($primary-background-color, $primary-background-transparency);
 }
 
+.video-js.vjs-spatial-navigation-enabled .vjs-control-bar {
+  gap: 1px;
+}
+
 // Locks the display only if:
 //  - controls are not disabled
 //  - native controls are not used

src/css/components/_slider.scss

@@ -18,3 +18,8 @@
 
   @include box-shadow(0 0 1em $primary-foreground-color);
 }
+
+// Replacement for focus in case spatial navigation is enabled
+.video-js.vjs-spatial-navigation-enabled .vjs-slider:focus {
+  outline: 0.0625em solid rgba($primary-foreground-color, 1);
+}

src/js/component.js

@@ -1283,6 +1283,49 @@
     return this.currentDimension('height');
   }
 
+  /**
+   * Retrieves the position and size information of the component's element.
+   *
+   * @return {Object} An object with `boundingClientRect` and `center` properties.
+   *         - `boundingClientRect`: An object with properties `x`, `y`, `width`,
+   *           `height`, `top`, `right`, `bottom`, and `left`, representing
+   *           the bounding rectangle of the element.
+   *         - `center`: An object with properties `x` and `y`, representing
+   *           the center point of the element. `width` and `height` are set to 0.
+   */
+  getPositions() {
+    const rect = this.el_.getBoundingClientRect();
+
+    // Creating objects that mirror DOMRectReadOnly for boundingClientRect and center
+    const boundingClientRect = {
+      x: rect.x,
+      y: rect.y,
+      width: rect.width,
+      height: rect.height,
+      top: rect.top,
+      right: rect.right,
+      bottom: rect.bottom,
+      left: rect.left
+    };
+
+    // Calculating the center position
+    const center = {
+      x: rect.left + rect.width / 2,
+      y: rect.top + rect.height / 2,
+      width: 0,
+      height: 0,
+      top: rect.top + rect.height / 2,
+      right: rect.left + rect.width / 2,
+      bottom: rect.top + rect.height / 2,
+      left: rect.left + rect.width / 2
+    };
+
+    return {
+      boundingClientRect,
+      center
+    };
+  }
+
   /**
    * Set the focus to this component
    */
@@ -1308,8 +1351,8 @@
     if (this.player_) {
 
       // We only stop propagation here because we want unhandled events to fall
-      // back to the browser. Exclude Tab for focus trapping.
-      if (!keycode.isEventKey(event, 'Tab')) {
+      // back to the browser. Exclude Tab for focus trapping, exclude also when spatialNavigation is enabled.
+      if (!keycode.isEventKey(event, 'Tab') && !(this.player_.options_.playerOptions.spatialNavigation && this.player_.options_.playerOptions.spatialNavigation.enabled)) {
         event.stopPropagation();
       }
       this.player_.handleKeyDown(event);
@@ -1765,6 +1808,154 @@
     });
   }
 
+  /**
+    * Decide whether an element is actually disabled or not.
+    *
+    * @function isActuallyDisabled
+    * @param element {Node}
+    * @return {boolean}
+    *
+    * @see {@link https://html.spec.whatwg.org/multipage/semantics-other.html#concept-element-disabled}
+    */
+  getIsDisabled() {
+    return Boolean(this.el_.disabled);
+  }
+
+  /**
+    * Decide whether the element is expressly inert or not.
+    *
+    * @see {@link https://html.spec.whatwg.org/multipage/interaction.html#expressly-inert}
+    * @function isExpresslyInert
+    * @param element {Node}
+    * @return {boolean}
+    */
+  getIsExpresslyInert() {
+    return this.el_.inert && !this.el_.ownerDocument.documentElement.inert;
+  }
+
+  /**
+   * Determine whether or not this component can be considered as focusable component.
+   *
+   * @param {HTMLElement} el - The HTML element representing the component.
+   * @return {boolean}
+   *         If the component can be focused, will be `true`. Otherwise, `false`.
+   */
+  getIsFocusable() {
+    return this.el_.tabIndex >= 0 && !(this.getIsDisabled() || this.getIsExpresslyInert());
+  }
+
+  /**
+   * Determine whether or not this component is currently visible/enabled/etc...
+   *
+   * @param {HTMLElement} el - The HTML element representing the component.
+   * @return {boolean}
+   *         If the component can is currently visible & enabled, will be `true`. Otherwise, `false`.
+   */
+  getIsAvailableToBeFocused(el) {
+    /**
+     * Decide the style property of this element is specified whether it's visible or not.
+     *
+     * @function isVisibleStyleProperty
+     * @param element {CSSStyleDeclaration}
+     * @return {boolean}
+     */
+    function isVisibleStyleProperty(element) {
+      const elementStyle = window.getComputedStyle(element, null);
+      const thisVisibility = elementStyle.getPropertyValue('visibility');
+      const thisDisplay = elementStyle.getPropertyValue('display');
+      const invisibleStyle = ['hidden', 'collapse'];
+
+      return (thisDisplay !== 'none' && !invisibleStyle.includes(thisVisibility));
+    }
+
+    /**
+     * Decide whether the element is being rendered or not.
+     * 1. If an element has the style as "visibility: hidden | collapse" or "display: none", it is not being rendered.
+     * 2. If an element has the style as "opacity: 0", it is not being rendered.(that is, invisible).
+     * 3. If width and height of an element are explicitly set to 0, it is not being rendered.
+     * 4. If a parent element is hidden, an element itself is not being rendered.
+     * (CSS visibility property and display property are inherited.)
+     *
+     * @see {@link https://html.spec.whatwg.org/multipage/rendering.html#being-rendered}
+     * @function isBeingRendered
+     * @param element {Node}
+     * @return {boolean}
+     */
+    function isBeingRendered(element) {
+      if (!isVisibleStyleProperty(element.parentElement)) {
+        return false;
+      }
+      if (!isVisibleStyleProperty(element) || (element.style.opacity === '0') || (window.getComputedStyle(element).height === '0px' || window.getComputedStyle(element).width === '0px')) {
+        return false;
+      }
+      return true;
+    }
+
+    /**
+     * Determine if the element is visible for the user or not.
+     * 1. If an element sum of its offsetWidth, offsetHeight, height and width is less than 1 is not visible.
+     * 2. If elementCenter.x is less than is not visible.
+     * 3. If elementCenter.x is more than the document's width is not visible.
+     * 4. If elementCenter.y is less than 0 is not visible.
+     * 5. If elementCenter.y is the document's height is not visible.
+     *
+     * @function isVisible
+     * @param element {Node}
+     * @return {boolean}
+     */
+    function isVisible(element) {
+      if ((element.offsetWidth + element.offsetHeight + element.getBoundingClientRect().height + element.getBoundingClientRect().width) === 0) {
+        return false;
+      }
+
+      // Define elementCenter object with props of x and y
+      // x: Left position relative to the viewport plus element's width (no margin) divided between 2.
+      // y: Top position relative to the viewport plus element's height (no margin) divided between 2.
+      const elementCenter = {
+        x: element.getBoundingClientRect().left + element.offsetWidth / 2,
+        y: element.getBoundingClientRect().top + element.offsetHeight / 2
+      };
+
+      if (elementCenter.x < 0) {
+        return false;
+      }
+      if (elementCenter.x > (document.documentElement.clientWidth || window.innerWidth)) {
+        return false;
+      }
+      if (elementCenter.y < 0) {
+        return false;
+      }
+      if (elementCenter.y > (document.documentElement.clientHeight || window.innerHeight)) {
+        return false;
+      }
+
+      let pointContainer = document.elementFromPoint(elementCenter.x, elementCenter.y);
+
+      while (pointContainer) {
+        if (pointContainer === element) {
+          return true;
+        }
+        if (pointContainer.parentNode) {
+          pointContainer = pointContainer.parentNode;
+        } else {
+          return false;
+        }
+
+      }
+    }
+
+    // If no DOM element was passed as argument use this component's element.
+    if (!el) {
+      el = this.el();
+    }
+
+    // If element is visible, is being rendered & either does not have a parent element or its tabIndex is not negative.
+    if (isVisible(el) && isBeingRendered(el) && ((!el.parentElement) || (el.tabIndex >= 0))) {
+      return true;
+    }
+    return false;
+  }
+
   /**
    * Register a `Component` with `videojs` given the name and the component.
    *

src/js/menu/menu-button.js

@@ -308,7 +308,7 @@
         this.menuButton_.focus();
       }
     // Up Arrow or Down Arrow also 'press' the button to open the menu
-    } else if (keycode.isEventKey(event, 'Up') || keycode.isEventKey(event, 'Down')) {
+    } else if ((keycode.isEventKey(event, 'Up') || keycode.isEventKey(event, 'Down')) && !(this.player_.options_.playerOptions.spatialNavigation && this.player_.options_.playerOptions.spatialNavigation.enabled)) {
       if (!this.buttonPressed_) {
         event.preventDefault();
         this.pressButton();

src/js/modal-dialog.js

@@ -21,7 +21,7 @@ const MODAL_CLASS_NAME = 'vjs-modal-dialog';
 class ModalDialog extends Component {
 
   /**
-   * Create an instance of this class.
+   * Creates an instance of this class.
    *
    * @param { import('./player').default } player
    *        The `Player` that this class should be attached to.
@@ -236,6 +236,7 @@ class ModalDialog extends Component {
     if (!this.opened_) {
       return;
     }
+
     const player = this.player();
 
     /**
@@ -265,8 +266,10 @@ class ModalDialog extends Component {
       *
       * @event ModalDialog#modalclose
       * @type {Event}
+      *
+      * @property {boolean} [bubbles=true]
       */
-    this.trigger('modalclose');
+    this.trigger({type: 'modalclose', bubbles: true});
     this.conditionalBlur_();
 
     if (this.options_.temporary) {
@@ -454,7 +457,13 @@ class ModalDialog extends Component {
    * @listens keydown
    */
   handleKeyDown(event) {
-
+    /**
+     * Fired a custom keyDown event that bubbles.
+     *
+     * @event ModalDialog#modalKeydown
+     * @type {Event}
+     */
+    this.trigger({type: 'modalKeydown', originalEvent: event, target: this, bubbles: true});
     // Do not allow keydowns to reach out of the modal dialog.
     event.stopPropagation();
 

src/js/player.js

@@ -36,6 +36,7 @@ import {hooks} from './utils/hooks';
 import {isObject} from './utils/obj';
 import keycode from 'keycode';
 import icons from '../images/icons.svg';
+import SpatialNavigation from './spatial-navigation.js';
 
 // The following imports are used only to ensure that the corresponding modules
 // are always included in the video.js package. Importing the modules will
@@ -562,6 +563,13 @@ class Player extends Component {
       this.addClass('vjs-audio');
     }
 
+    // Check if spatial navigation is enabled in the options.
+    // If enabled, instantiate the SpatialNavigation class.
+    if (options.spatialNavigation && options.spatialNavigation.enabled) {
+      this.spatialNavigation = new SpatialNavigation(this);
+      this.addClass('vjs-spatial-navigation-enabled');
+    }
+
     // TODO: Make this smarter. Toggle user state between touching/mousing
     // using events, since devices can have both touch and mouse events.
     // TODO: Make this check be performed again when the window switches between monitors
@@ -5447,6 +5455,10 @@ Player.prototype.options_ = {
   responsive: false,
   audioOnlyMode: false,
   audioPosterMode: false,
+  spatialNavigation: {
+    enabled: false,
+    horizontalSeek: false
+  },
   // Default smooth seeking to false
   enableSmoothSeeking: false
 };

src/js/slider/slider.js

@@ -308,14 +308,32 @@
    * @listens keydown
    */
   handleKeyDown(event) {
-
-    // Left and Down Arrows
-    if (keycode.isEventKey(event, 'Left') || keycode.isEventKey(event, 'Down')) {
+    const spatialNavOptions = this.options_.playerOptions.spatialNavigation;
+    const spatialNavEnabled = spatialNavOptions && spatialNavOptions.enabled;
+    const horizontalSeek = spatialNavOptions && spatialNavOptions.horizontalSeek;
+
+    if (spatialNavEnabled) {
+      if ((horizontalSeek && keycode.isEventKey(event, 'Left')) ||
+        (!horizontalSeek && keycode.isEventKey(event, 'Down'))) {
+        event.preventDefault();
+        event.stopPropagation();
+        this.stepBack();
+      } else if ((horizontalSeek && keycode.isEventKey(event, 'Right')) ||
+        (!horizontalSeek && keycode.isEventKey(event, 'Up'))) {
+        event.preventDefault();
+        event.stopPropagation();
+        this.stepForward();
+      } else {
+        super.handleKeyDown(event);
+      }
+
+      // Left and Down Arrows
+    } else if (keycode.isEventKey(event, 'Left') || keycode.isEventKey(event, 'Down')) {
       event.preventDefault();
       event.stopPropagation();
       this.stepBack();
 
-    // Up and Right Arrows
+      // Up and Right Arrows
     } else if (keycode.isEventKey(event, 'Right') || keycode.isEventKey(event, 'Up')) {
       event.preventDefault();
       event.stopPropagation();