@gilchrist/spacnav 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# Spatnav — HTMLElement bindings for generic spatial navigation
+
+Spatial navigation is a means of navigating focusable elements in
+an interface based on their positions, relative to one another.
+Pressing up should move you upward, right should move you rightward, and
+so on.
+
+Spacnav, short for Spatial Navigation, is a series of function
+bindings for `HTMLElement`s which provide spatial navigation
+functionality. It was initially written for my web-based
+roguelike game, but I split off the code into its own project.
+Currently, this library's development is coupled to that game
+project, but I am intending to isolate the code more over time.
+
+There is a W3C spec draft the for the feature, but no official
+spatial navigation functionality exists in browsers. This
+implementation does not follow the W3C draft, and currently, it
+does not implement any CSS properties to control spatial
+navigation. It also does not set or define any event handling
+functions. The developer must call the spatial navigation methods
+and implement event handling themselves. Over time, it may get
+reworked and move closer to that specification.
+
+## Initialization
+
+The library does not automatically bind functions to
+`HTMLElement`. Instead, call the default export,
+`initSpacnavElementMethods()`. This function is idempotent.
+
+```html
+<script>
+  import initSpacnavElementMethods from "spatnav.js";
+  initSpacnavElementMethods();
+</script>
+```
+
+## Using spatnav methods
+
+This module adds several methods to `HTMLElement`.
+
+### `isSelectable()`
+
+Returns `true` if the element can be focused via spatial
+navigation. By default, this includes `<button>` elements, or any
+element with the class `button` or `selectable`, or the
+attributes `selectable` or `button`.
+
+*note*: At a later point, these classes and attributes may be
+replaced with CSS properties, similar to the W3C specification
+draft.
+
+### `findSpacnavElement(direction_or_theta)`
+
+Finds the lowest-scoring candidate for spatial navigation in a
+given direction.
+
+- `direction_or_theta`: Can be a numeric angle in radians or a
+  directional vector in the form of a 2-element `Array`: `[dx, dy]`.
+- Returns the `HTMLElement` with the lowest score, or `null` if
+  no suitable candidate is found.
+
+### `handleSelect(previous_selection)`
+
+Standard handler for selecting an element. It calls
+`handleDeselect()` on the `previous_selection` (if provided),
+focuses the current element, and scrolls it into view.
+
+### `handleDeselect()`
+
+Standard handler for deselecting an element. By default, it calls
+`this.blur()`.
+
+### `isSpacnavContainer()`
+
+Returns `true` if the element is marked as a spatial navigation
+container (has class `spacnav-container`, `spacnav-context`, or
+`menu`). Containers help organize and limit the scope of spatial
+navigation.
+
+*note*: The `menu` class will be removed from this module,
+as it is specific to the game code this module is based on.
+
+### `getSpacnavContainer()`
+
+Returns the closest parent element that is a spatial navigation
+container.
+
+### `iterSpacnavCandidates()`
+
+A generator that yields all selectable elements or nested
+containers within the current container. It does not recurse into
+nested containers but yields the containers themselves if they
+are selectable.
+
+### `getSpacnavDistanceTo(direction, candidate)`
+
+Calculates a "distance" score to a candidate element in a
+specific direction.  This is used internally by
+`findSpacnavElement` to determine the best next element. Lower
+scores are better. It returns `null` if the candidate is not in
+the specified direction or exceeds the angular threshold.
+
+## Configuration
+
+### `spacnav-threshold` attribute
+
+You can control how "wide" the search beam is by setting the
+`spacnav-threshold` attribute on an element or any of its
+parents.
+
+- Value can be in radians (e.g., `1.57`) or degrees (e.g., `90deg`).
+- Default is `2π/3` (approx 120 degrees).
+
+## Tests
+
+Automated testing is done with vitest and playwright in a
+headless Chrome instance. To run tests, install NPM packages and
+run the NPM test script:
+```bash
+npm i
+npm test
+```
+
+## Credits
+
+`spacnav` was developed by [Gilchrist
+Pitts](https://gilchrist.tech), initially for a web-based game
+project.
+
+Originally, it was made as an attempt to modify the algorithm in
+the CSS Spatial Navigation Module Level 1 specification draft:
+* [https://drafts.csswg.org/css-nav-1/](https://drafts.csswg.org/css-nav-1/)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@gilchrist/spacnav",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "spacnav.js",
+  "scripts": {
+    "test": "vitest run",
+    "dev":  "vitest"
+  },
+  "keywords": [
+    "spatial",
+    "navigation",
+    "browser"
+  ],
+  "author": "Gilchrist Pitts",
+  "license": "MIT",
+  "description": "HTMLElement bindings for spatial navigation",
+  "devDependencies": {
+    "@vitest/browser-playwright": "^4.1.2",
+    "vitest": "^4.1.2"
+  }
+}

package/spatnav.js

@@ -0,0 +1,631 @@
+function pointInRect (x, y, rx, ry, rw, rh) {
+  return (
+    rx <= x && x < rx + rw &&
+    ry <= y && y < ry + rh
+  );
+}
+
+
+function minWhere (func) {
+  let min       = arguments[1];
+  let min_where = func(min);
+
+  for (let i=2; i < arguments.length; i++) {
+    const where = func(arguments[i]);
+
+    if (where < min_where) {
+      min       = arguments[i];
+      min_where = where;
+    }
+  }
+
+  return min;
+}
+
+
+function distance2 (x1, y1, x2, y2) {
+  switch (arguments.length) {
+    case 2:
+      return (
+        Math.pow(arguments[1][0] - arguments[0][0], 2) +
+        Math.pow(arguments[1][1] - arguments[0][1], 2)
+      );
+    case 4:
+      return (
+        Math.pow(x2 - x1, 2) +
+        Math.pow(y2 - y1, 2)
+      );
+    default:
+      throw new TypeError(`distance2() requires 2 or 4 arguments, got ${arguments.length}`);
+  }
+}
+
+
+function parseArgsThetaOrVector (theta_or_dx, dy) {
+  let dx;
+  let dt;
+
+  switch (arguments.length) {
+    case 1:
+      if (typeof theta_or_dx === "number") {
+        if (Number.isNaN(theta_or_dx)) {
+          throw new TypeError("First argument is NaN");
+        }
+
+        dx = Math.cos(theta_or_dx);
+        dy = Math.sin(theta_or_dx);
+        dt = theta_or_dx;
+
+      } else if (Array.isArray(theta_or_dx)) {
+        [dx, dy] = theta_or_dx;
+        dt = Math.atan2(dy, dx);
+
+      } else {
+        throw new TypeError(
+          `Expected single argument to be a finite number or Array of finite numbers, got ${
+            theta_or_dx?.constructor?.name ?? typeof theta_or_dx
+          }`
+        );
+      }
+      break;
+
+    case 2:
+      dx = theta_or_dx;
+      dt = Math.atan2(dy, dx);
+      break;
+
+    default:
+      throw new TypeError(`expects one or two arguments, got ${arguments.length}`);
+  }
+
+  return { dx, dy, dt };
+}
+
+
+export function getElementSpacnavThreshold (element) {
+  let default_threshold = 2*Math.PI/3;
+
+  if ("spacnav-threshold" in element.attributes) {
+    let threshold_attr  = element.getAttribute("spacnav-threshold");
+    let threshold_float = parseFloat(threshold_attr); // note: this ignores degrees suffix
+
+    // An empty spacnav_threshold resets the default value
+    if (threshold_attr == "") {
+      return default_threshold;
+    }
+
+    if (! Number.isFinite(threshold_float)) {
+      throw new TypeError(`Expected spacnav-threshold attribute to contain a finite float, got ${
+        threshold_float?.constructor?.name ?? typeof threshold_float
+      }`);
+    }
+
+    if (threshold_attr.endsWith("deg")) {
+      return threshold_float / 180 * Math.PI;
+    } else {
+      return threshold_float;
+    }
+
+  } else {
+    // The spacnav-threshold attribute was not found in this
+    // element. Traverse parent containers looking for a defined
+    // threshold, or go with the 90-degree default value.
+
+    if (element.parentElement) {
+      return getElementSpacnavThreshold(element.parentElement);
+    } else {
+      return default_threshold;
+    }
+
+  }
+}
+
+
+export function isSelectable () {
+  return (
+    this.tagName === "BUTTON"              ||
+    this.classList.contains("button")      ||
+    this.classList.contains("selectable")  ||
+    this.hasAttribute("selectable")        ||
+    this.hasAttribute("button")
+  );
+};
+
+
+export function getSpacnavContainer () /* HTMLElement */ {
+  let element;
+
+  for (
+    element = this.parentElement;
+    element;
+    element = element.parentElement
+  ) if (
+    element.isSpacnavContainer()
+  ){
+    return element;
+  }
+
+  return null;
+};
+
+
+export function getSpacnavContext () /* HTMLElement */ {
+  // Get the selection context element. All spatial navigation
+  // logic should be constrained to the current selection
+  // context.
+
+  let element;
+
+  for (
+    element = this.parentElement;
+    element;
+    element = element.parentElement
+  ) if (
+    element.isSpacnavContext()
+  ){
+    return element;
+  }
+
+  if (document.body.contains(this)) {
+    return document.body;
+  }
+
+  return null;
+};
+
+
+export function isSpacnavContext () {
+  return (
+    this.classList.contains("spacnav-context") ||
+    this.classList.contains("menu")
+  );
+};
+
+
+export function isSpacnavContainer () {
+  return (
+    this.classList.contains("spacnav-container") ||
+    this.classList.contains("spacnav-context") ||
+    this.classList.contains("menu")
+  );
+};
+
+
+export function handleDeselect () {
+  this.blur();
+};
+
+
+export function handleSelect (previous_selection) {
+  if (! (previous_selection instanceof HTMLElement || previous_selection == null)) {
+    throw new TypeError(`Expected previous_selection to be nullish or an HTMLElement, got ${
+      previous_selection?.constructor?.name ?? typeof previous_selection
+    }`);
+  }
+
+  previous_selection?.handleDeselect();
+
+  this.focus();
+  this.scrollIntoView({
+      behavior: "smooth",
+      block:    "center",
+      inline:   "center",
+    });
+};
+
+export function findSpacnavElement (theta_or_dx, dy) /* HTMLElement */ {
+  const found = this.findSpacnavElementWithinContext(null, ...arguments);
+
+  if (found) {
+    return found;
+  }
+
+  return this.getSpacnavContainer()?.findSpacnavElementWithinContext(null, ...arguments) ?? null;
+};
+
+export function findSpacnavElementWithinContext (selection_context, theta_or_dx, dy) /* HTMLElement */ {
+  if (arguments.length < 2 || arguments.length > 3) {
+    throw new TypeError(`Expected 2-3 arguments, got ${arguments.length}`);
+  }
+
+  var { dx, dy, dt } = parseArgsThetaOrVector(...Array.from(arguments).slice(1));
+
+  let selection_container;
+  let reference_selection_container;
+
+  if (selection_context === null) {
+    selection_context   = this.getSpacnavContext();
+    selection_container = this.getSpacnavContainer();
+    reference_selection_container = selection_container;
+
+    if (!selection_container)
+      return null;
+
+  } else {
+    selection_container = selection_context;
+    reference_selection_container = this.getSpacnavContainer();
+  }
+
+  const rect = this.getBoundingClientRect();
+
+  // Start raycasting from the intersection of the raycasting
+  // vector and this element's perimeter.
+  let start_x = rect.x + rect.width /2;
+  let start_y = rect.y + rect.height/2;
+
+  // Determine where the ray leaves this element's bounding box.
+  // TODO: use math to calculate this instead of raycasting
+
+  while (pointInRect(
+    start_x + dx, start_y + dy,
+    rect.x, rect.y, rect.width, rect.height,
+  )) {
+    start_x += dx;
+    start_y += dy;
+  }
+
+  const searched_selection_containers = new Set();
+
+  let step_length = 8;
+  let max_steps   = 2000/step_length;  // TODO: could fail on large screen sizes. Maybe depend on viewport size?
+  let element     = null;
+  let num_steps   = 0;
+
+  // Check up the selection container chain
+
+  let min_distance  = null;
+  let min_candidate = null;
+
+  for (
+    let checked = new Set([ this ]);
+
+    selection_container && (
+      ! selection_context ||
+      selection_container === selection_context ||
+      selection_context.contains(selection_container)
+    );
+
+    /* handled below: if selection_container === selection_context, this is the last iteration */
+
+    checked.add(selection_container),
+    selection_container = selection_container.getSpacnavContainer()
+  ){
+    for (let candidate of selection_container.iterSpacnavCandidates()) {
+      if (checked.has(candidate)) {
+        continue;
+      }
+
+      const distance = this.getSpacnavDistanceTo(dt, candidate);
+
+      if (distance === null) {
+        continue;
+      }
+
+      const is_same_selection_container = (candidate.getSpacnavContainer() === reference_selection_container);
+
+      if (candidate.hasAttribute("spacnav-internal") && !is_same_selection_container) {
+        continue;
+      }
+
+      if (!min_candidate || distance < min_distance) {
+        let new_min_candidate = candidate;
+
+        if (candidate.isSpacnavContainer()) {
+          new_min_candidate = this.findSpacnavElementWithinContext(candidate, dx, dy);
+
+          if (candidate.isSelectable()) {
+            new_min_candidate ??= candidate;
+          }
+        }
+
+        if (new_min_candidate) {
+          min_distance  = distance;
+          min_candidate = new_min_candidate;
+        }
+      }
+    }
+
+    checked.add(selection_container);
+
+    if (selection_container === selection_context) {
+      break;
+    }
+
+    if (min_candidate) {
+      break;
+    }
+  }
+
+  switch (min_candidate?.getAttribute("spacnav-refer")) {
+    case "score":
+      // TODO: how does the logic of this work with non-selectable selection containers?
+      min_candidate = this.getSpacnavDistanceToWithinContext(min_candidate, dx, dy);
+      break;
+
+    case "first":
+      min_candidate = candidate.querySelector("selectable, button");
+      throw new Error("[spacnav-refer=first] not yet implemented");
+  }
+
+  return min_candidate; // Return the best candidate after checking all containers
+};
+
+
+export function * iterSpacnavContainers () {
+  if (!this.isSpacnavContainer()) {
+    return null;
+  }
+
+  for (
+    let next, el = this.firstElementChild;
+    el && el !== this;
+    el = next
+  ){
+    if (el.isSpacnavContainer()) {
+      yield el;
+      next = el.nextElementSibling;
+    } else if (el.isSelectable()) {
+      next = el.nextElementSibling;
+    } else {
+      next = el.firstElementChild ??
+             el.nextElementSibling;
+    }
+
+    // Search for an uncle element (sibling of the parent)
+    for (
+      let parent = el.parentElement ;
+      !next && parent && parent !== this;
+      parent = parent.parentElement
+    ){
+      next = parent.nextElementSibling;
+    }
+  }
+}
+
+
+export function * iterSpacnavCandidates () /* yields HTMLElement */ {
+  if (!this.isSpacnavContainer()) {
+    return null;
+  }
+
+  for (
+    let next, el = this.firstElementChild;
+    el && el !== this;
+    el = next
+  ){
+    if (
+      el.isSpacnavContainer() ||
+      el.isSelectable()
+    ){
+      yield el;
+      next = el.nextElementSibling;
+
+    } else {
+      next = el.firstElementChild ??
+             el.nextElementSibling ;
+    }
+
+    // Search for an uncle element (sibling of the parent)
+    for (
+      let parent = el.parentElement ;
+      !next && parent && parent !== this;
+      parent = parent.parentElement
+    ){
+      next = parent.nextElementSibling;
+    }
+  }
+};
+
+
+export function getSpacnavDistanceTo (direction, candidate) {
+  switch (arguments.length) {
+    case 3:
+      direction = [arguments[0], arguments[1]];
+      candidate = arguments[2];
+    case 2:
+      break;
+
+    default:
+      throw new TypeError(`getSpacnavDistanceTo() expects 2-3 arguments, got ${arguments.length}`);
+  }
+
+  if ( ! (candidate instanceof HTMLElement)) {
+    throw new TypeError(`getSpacnavDistanceTo() expects candidate to be an HTMLElement, got ${
+      candidate?.constructor?.name ?? typeof candidate
+    }`);
+  }
+
+  // Variable naming convention: this function uses naming
+  // conventions which are usually frowned upon in programming
+  // contexts, with the names being notably short and having
+  // single-leter components. However, due to the amount of
+  // math, it is used with a local naming convention.
+
+  // Variables beginning with a capital letter refer to a
+  // thing within the spatial navigation's evaluatory context.
+  //
+  // The important ones here are as follows:
+
+  //   R  Reference, `this`, the element from whom the spatial
+  //      navigation originates.
+
+  //   C  Candidate, the element whose spatial navigation
+  //      distance from the Reference is being evaluated.
+
+  //   B  Beam, an infinite, monodirectional line with an
+  //      origin point on the reference, pointing in the direction
+  //      of the spatial navigation. The origin is on the
+  //      perimeter of the reference.
+
+  //   P  Projection, which refers to a point on the
+  //      candidate's perimeter, as well as the trajectory to
+  //      that point.
+
+  // Beam's directional x-y vector and theta (angle)
+  let Bdx, Bdy, Bdt;
+
+  if (Array.isArray(direction)) {
+    if (direction.length !== 2) {
+      throw new TypeError(`getSpacnavDistanceTo() expects an array with a length of two, got ${direction.length}`);
+    }
+
+    [Bdx, Bdy] = direction;
+
+    if (! Number.isFinite(Bdx) || ! Number.isFinite(Bdy)) {
+      throw new TypeError("getSpacnavDistanceTo() expects an array with two finite numbers");
+    }
+
+    Bdt = Math.atan2(Bdy, Bdx);
+
+  } else if (typeof direction === "number") {
+    if (! Number.isFinite(direction)) {
+      throw new TypeError("getSpacnavDistanceTo() expects a number denoting direction, but it is not finite");
+    }
+
+    Bdt = direction;
+    Bdx = Math.cos(Bdt);
+    Bdy = Math.sin(Bdt);
+
+  } else {
+    throw new TypeError(`getSpacnavDistance() to expects direction to by an Array of two finite numbers (a directional vector) or a finite number (angle in radians), got ${
+      direction?.constructor?.name ?? typeof direction
+    }`);
+  }
+
+  // Candidate and reference rectangular bounds
+  const Rr  = this.getBoundingClientRect();
+  const Cr  = candidate.getBoundingClientRect();
+  const Rw  = Rr.width,     Rh  = Rr.height;    // Size shorthands
+  const Cw  = Cr.width,     Ch  = Cr.height;
+  const Rcx = Rr.x + Rw/2,  Rcy = Rr.y + Rh/2;  // Rect centers
+  const Ccx = Cr.x + Cw/2,  Ccy = Cr.y + Ch/2;
+
+  /*
+    Calculate a point on the perimeter of the reference,
+    opposite the direction of the beam, and intersecting with
+    the center of the reference, like so:
+
+      ----------
+      |        |
+    --B---Rc---|---->
+      |        |
+      ----------
+      ^^^^^
+      RBd: distance between the reference center and beam origin
+  */
+
+  // Distance between reference center and beam origin
+  const RBd = Math.min(Math.abs(Rw/(Bdx || 0.0000001)), Math.abs(Rh/(Bdy || 0.0000001)))/2;
+  const Bx  = Rcx - RBd*Bdx;
+  const By  = Rcy - RBd*Bdy;
+
+  /*
+      ----------
+      |        |     ---------
+    --B---Rc---|---->P       |--->
+      |        |     |   Cc  |
+      ----------     |       |
+                     ---------
+  */
+
+  // Candidate rectangle's edge shorthands
+  const C_top = Cr.top ,  C_bot = Cr.bottom ;
+  const C_lft = Cr.left,  C_rgt = Cr.right  ;
+
+  if (!Number.isFinite(Bdx)) throw new Error("");
+
+  // t-values along each edge (when extrapolated to being an
+  // infinite line), where the beam intersects that edge.
+  const C_lft_t = (Bx - C_lft) / (Bdx || 0.000001), C_rgt_t = (Bx - C_rgt) / (Bdx || 0.000001) ;
+  const C_top_t = (By - C_top) / (Bdy || 0.000001), C_bot_t = (By - C_bot) / (Bdy || 0.000001) ;
+
+  // Find the candidate edge intersection t-values, horizontal and vertical, which are nearest to 
+  const Peh_t = minWhere(Math.abs, ...[C_top_t, C_bot_t]);
+  const Pev_t = minWhere(Math.abs, ...[C_lft_t, C_rgt_t]);
+
+  // Candidate horizontal and vertical edge intersection positions
+  const Phy = (Peh_t === C_top_t ? C_top : C_bot);
+  const Pvx = (Pev_t === C_lft_t ? C_lft : C_rgt);
+  const Phx = Bx - Peh_t*Bdx;
+  const Pvy = By - Pev_t*Bdy;
+
+  const Ph_in_bounds               = (C_lft <= Phx && Phx <= C_rgt);
+  const Pv_in_bounds               = (C_top <= Pvy && Pvy <= C_bot);
+  const P_use_nearest_intersection = !(Ph_in_bounds ^ Pv_in_bounds);
+
+  let Px, Py;
+
+  if (P_use_nearest_intersection) {
+    [Px, Py] = minWhere(
+      ([px, py]) => distance2(px, py, Bx, By),
+      [Phx, Phy], [Pvx, Pvy],
+    );
+
+    if (Px == undefined || Py == undefined) {
+      return null;
+    }
+
+  } else if (Ph_in_bounds) {
+    Px = Phx;
+    Py = Phy;
+
+  } else /* Pv_in_bounds */ {
+    Px = Pvx;
+    Py = Pvy;
+  }
+
+  Px = Math.min(C_rgt, Math.max(C_lft, Px));
+  Py = Math.min(C_bot, Math.max(C_top, Py));
+
+  const projected_angular_displacement = Math.abs( Math.PI * Math.sin(
+      Math.abs(Math.atan2(Py-By, Px-Bx) - Bdt) / 2
+    ));
+
+  const threshold = getElementSpacnavThreshold(this);
+
+  const projected_euclidean_distance = Math.sqrt(distance2(Bx, By, Px, Py));
+
+  const Bd = (Px-Bx)*Bdx + (Py-By)*Bdy;
+
+  if (
+    projected_euclidean_distance == 0 ||
+    Bd < 0 ||
+    projected_angular_displacement > threshold
+  ){
+    return null;
+  }
+
+  const projected_angular_displacement_weight_curving = 1.6;
+  const projected_angular_displacement_weight = Math.pow(
+    Math.abs(projected_angular_displacement - threshold),
+    projected_angular_displacement_weight_curving
+  );
+
+  const beam_distance_weight = 0.5;
+
+  const distance = (
+    Bd * beam_distance_weight +
+    projected_euclidean_distance / (1+projected_angular_displacement_weight)
+  );
+
+  if (!Number.isFinite(distance)) {
+    throw new Error(`Distance is not finite, got ${distance}. Something should be debugged.`);
+  }
+  return distance;
+};
+
+
+export function initSpacnavElementMethods () /* void */ {
+  HTMLElement.prototype.isSelectable                    = isSelectable;
+  HTMLElement.prototype.getSpacnavContainer             = getSpacnavContainer;
+  HTMLElement.prototype.getSpacnavContext               = getSpacnavContext;
+  HTMLElement.prototype.isSpacnavContext                = isSpacnavContext;
+  HTMLElement.prototype.isSpacnavContainer              = isSpacnavContainer;
+  HTMLElement.prototype.handleDeselect                  = handleDeselect;
+  HTMLElement.prototype.handleSelect                    = handleSelect;
+  HTMLElement.prototype.findSpacnavElement              = findSpacnavElement;
+  HTMLElement.prototype.findSpacnavElementWithinContext = findSpacnavElementWithinContext;
+  HTMLElement.prototype.iterSpacnavContainers           = iterSpacnavContainers;
+  HTMLElement.prototype.iterSpacnavCandidates           = iterSpacnavCandidates;
+  HTMLElement.prototype.getSpacnavDistanceTo            = getSpacnavDistanceTo;
+}

package/spatnav.test.js

@@ -0,0 +1,341 @@
+import { describe, test, it, expect, beforeEach, vi } from "vitest";
+import { initSpacnavElementMethods } from "./spatnav.js";
+
+// Set up a basic DOM environment for each test
+beforeEach(() => {
+  document.body.innerHTML = (`
+    <style>
+      *, *::before, *::after { box-sizing: inherit; }
+
+      body {
+        box-sizing: content-box;
+        margin: 0;
+      }
+    </style>
+  `);
+ 
+  document.body.classList.add("spacnav-container");
+
+  // Initialize the spatial navigation methods on HTMLElement.prototype
+  initSpacnavElementMethods();
+});
+
+
+function makeRectElement(rect={}, isSelectable = false, is_selection_container = false) {
+  const element = document.createElement("div");
+
+  element.style.position = "absolute";
+  element.style.left     = `${rect.left ?? rect.x ??  0 }px`;
+  element.style.top      = `${rect.top  ?? rect.y ??  0 }px`;
+  element.style.width    = `${rect.width          ?? 10 }px`;
+  element.style.height   = `${rect.height         ?? 10 }px`;
+  element.style.overflow = "hidden";
+
+  element.textContent = rect.text;
+
+  if (isSelectable) {
+    element.setAttribute("selectable", "");
+  }
+  if (is_selection_container) {
+    element.classList.add("spacnav-container");
+  }
+
+  document.body.appendChild(element);
+  return element;
+}
+
+
+test("Element rect positioning (test internal)", () => {
+  const rect = { x: 100, y: 200, width: 400, height: 300 };
+  const el   = makeRectElement(rect);
+  expect(el.getBoundingClientRect()).toMatchObject(rect);
+});
+
+
+test("HTMLElement.prototype.isSelectable", () => {
+  expect(document.createElement("div").isSelectable()).toBe(false);
+  expect(document.createElement("button").isSelectable()).toBe(true);
+
+  const div_class_button = document.createElement("div");
+  div_class_button.classList.add("button");
+  expect(div_class_button.isSelectable()).toBe(true);
+
+  const div_attribute_button = document.createElement("div");
+  div_attribute_button.toggleAttribute("button");
+
+  expect(div_attribute_button.isSelectable()).toBe(true);
+});
+
+
+describe("HTMLElement.prototype.isSpacnavContainer", () => {
+  it("should return true for an element with class 'spacnav-container'", () => {
+    const div = document.createElement("div");
+    div.classList.add("spacnav-container");
+    expect(div.isSpacnavContainer()).toBe(true);
+  });
+
+  it("should return true for an element with class 'menu'", () => {
+    const div = document.createElement("div");
+    div.classList.add("menu");
+    expect(div.isSpacnavContainer()).toBe(true);
+  });
+
+  it("should return false for a non-container element", () => {
+    const div = document.createElement("div");
+    expect(div.isSpacnavContainer()).toBe(false);
+  });
+});
+
+
+describe("HTMLElement.prototype.getSpacnavContainer", () => {
+  it("should return the parent selection container", () => {
+    const container = document.createElement("div");
+    container.classList.add("spacnav-container");
+    const child = document.createElement("div");
+    container.appendChild(child);
+
+    expect(child.getSpacnavContainer()).toBe(container);
+  });
+
+  it("should return the closest selection container when nested", () => {
+    const grandparent = makeRectElement({}, false, true);
+    const parent      = document.createElement("div");
+    const child       = makeRectElement({}, true, false);
+
+    grandparent.appendChild(parent);
+    parent.appendChild(child);
+
+    expect(child.getSpacnavContainer()).toBe(grandparent);
+  });
+
+  it("should return null if no selection container is found", () => {
+    const div = document.createElement("div");
+    expect(div.getSpacnavContainer()).toBe(null);
+  });
+});
+
+
+describe("HTMLElement.prototype.handleSelect and handleDeselect", () => {
+  it("handleSelect should focus the element and scroll it into view", () => {
+    const element = document.createElement("button");
+
+    const focus_spy  = vi.spyOn(element, "focus");
+    const scroll_spy = vi.spyOn(element, "scrollIntoView");
+
+    element.handleSelect(null);
+
+    expect(focus_spy).toHaveBeenCalledTimes(1);
+    expect(scroll_spy).toHaveBeenCalledWith({
+      behavior: "smooth",
+      block:    "center",
+      inline:   "center",
+    });
+
+    focus_spy.mockRestore();
+    scroll_spy.mockRestore();
+  });
+
+  it("handleDeselect should blur the element", () => {
+    const element = document.createElement("button");
+
+    const blur_spy = vi.spyOn(element, "blur");
+    element.handleDeselect();
+
+    expect(blur_spy).toHaveBeenCalledTimes(1);
+    blur_spy.mockRestore();
+  });
+
+  it("handleSelect should call handleDeselect on previous selection if provided", () => {
+    const previous_selection = document.createElement("button");
+    const current_selection  = document.createElement("button");
+
+    const deselect_spy = vi.spyOn(previous_selection, "handleDeselect");
+
+    current_selection.handleSelect(previous_selection);
+
+    expect(deselect_spy).toHaveBeenCalledTimes(1);
+    deselect_spy.mockRestore();
+  });
+});
+
+
+describe("HTMLElement.prototype.iterSpacnavCandidates", () => {
+  it("yields selectable direct children of the selection container", () => {
+    const container = makeRectElement({}, false, true);
+    const button_1  = document.createElement("button");
+    const div_1     = document.createElement("div"); div_1.toggleAttribute("selectable");
+    const button_2  = document.createElement("button");
+
+    container.appendChild(button_1);
+    container.appendChild(div_1);
+    container.appendChild(button_2);
+
+    const candidates = Array.from(container.iterSpacnavCandidates());
+    expect(candidates).toEqual([button_1, div_1, button_2]);
+  });
+
+  it("yields selectable elements inside nested non-selection container elements", () => {
+    const root_container = document.createElement("div");
+    document.body.appendChild(root_container);
+
+    root_container.outerHTML = `
+      <div id="container" class="spacnav-container">
+        <div id="div_1">
+          <button id="button_1"></button>
+          <button id="button_2"></button>
+          <div id="div_2">
+            <button id="button_3"></button>
+          </div>
+        </div>
+      </div>
+    `;
+
+    document.body.appendChild(root_container);
+
+    const candidates = Array.from(window.container.iterSpacnavCandidates());
+
+    expect(candidates).toEqual([
+      window.button_1,
+      window.button_2,
+      window.button_3
+    ]);
+  });
+
+  it("does not traverse into nested selection containers, but yields the container itself if selectable", () => {
+    document.body.innerHTML = `
+      <div id="container" class="spacnav-container">
+        <div id="selectable_container" class="spacnav-container selectable">
+          <button></button>
+        </div>
+      </div>
+    `;
+
+    const candidates = Array.from(
+      window.container.iterSpacnavCandidates()
+    );
+    expect(candidates).toEqual([window.selectable_container]);
+  });
+
+  it("should not traverse into nested selection containers if the container is not selectable", () => {
+    const container                = document.createElement("div");
+    const non_selectable_container = makeRectElement({}, false, true);
+    const button_inside            = document.createElement("button");
+    non_selectable_container.appendChild(button_inside);
+
+    container.appendChild(non_selectable_container);
+
+    const candidates = Array.from(container.iterSpacnavCandidates());
+    expect(candidates).toEqual([]);
+  });
+
+  it("should handle empty container", () => {
+    const container  = document.createElement("div");
+    const candidates = Array.from(container.iterSpacnavCandidates());
+    expect(candidates).toEqual([]);
+  });
+});
+
+
+describe("HTMLElement.prototype.findSpacnavElement", () => {
+  it("should return null if no selection container is found", () => {
+    const ref_element = makeRectElement();
+    const found_element = ref_element.findSpacnavElement(0);
+    expect(found_element).toBeNull();
+  });
+
+  it("returns the candidate with the minimum spatial navigation distance", () => {
+    const ref_element = makeRectElement({ text: "reference" }, true);
+
+    makeRectElement({ text: "further away",   x:  50 }, true);
+    makeRectElement({ text: "behind",         x: -10 }, true);
+    makeRectElement({ text: "not selectable", x:  10 }, false);
+    makeRectElement({ text: "up",             y:  10 }, true);
+    makeRectElement({ text: "diagonal",       x: 10,    y: 20 }, true);
+
+    const closest_element = makeRectElement({ text: "closest", x:  20 }, true);
+
+    const found_element = ref_element.findSpacnavElement(0);
+    expect(found_element?.textContent).toBe("closest");
+  });
+
+  it("should consider candidates from parent selection containers when none are found", () => {
+    const ref_element         = makeRectElement();
+    const child_container     = makeRectElement({ x: -10,  y:  -10, width:  30, height:  30 }, false, true);
+    const parent_container    = makeRectElement({ x: -100, y: -100, width: 200, height: 200 }, false, true);
+    const candidate_in_child  = makeRectElement({ x:  -20, y:    0, width:  10, height:  10 }, true);
+    const candidate_in_parent = makeRectElement({ x:   10, y:    0, width:  10, height:  10 }, true);
+
+    child_container.appendChild(ref_element);
+    parent_container.appendChild(child_container);
+    child_container.appendChild(candidate_in_child);
+    parent_container.appendChild(candidate_in_parent);
+
+    const found_element = ref_element.findSpacnavElement(0);
+    expect(found_element).toEqual(candidate_in_parent);
+  });
+
+  it("navigates to selectable items inside sibling selection containers, from an element inside another container", () => {
+    const sibling_container = makeRectElement({
+      text: "sibling-container",
+      x: 10, y: 30, w: 80, h: 45,
+    }, false, true);
+
+    const sibling_intermediate_wrapper = makeRectElement({
+      text: "sibling-intermediate-wrapper",
+      x: 10, y: 30, w: 80, h: 45,
+    }, false, false);
+
+    const reference_container = makeRectElement(
+      { text: "reference", x: 100, width: 100, height: 100 }, false, true
+    );
+
+    const child_a = makeRectElement({ text: "c1", x: 15, y: 35, w: 70, h: 15 }, true)
+    const child_b = makeRectElement({ text: "c2", x: 15, y: 55, w: 70, h: 15 }, true)
+
+    const ref = makeRectElement(
+      { text: "reference", x: 100, height: 100 }, true
+    );
+
+    sibling_container.appendChild(sibling_intermediate_wrapper);
+    sibling_intermediate_wrapper.appendChild(child_a);
+    sibling_intermediate_wrapper.appendChild(child_b);
+    reference_container.appendChild(ref);
+
+    const found = ref.findSpacnavElement(Math.PI);
+
+    expect(found, "expected to find one of the child elements").not.toBe(null);
+    expect(found.textContent.startsWith("c")).toBe(true);
+    expect(sibling_container.contains(found)).toBe(true);
+  });
+
+  it("navigates to selectable items inside sibling selection containers", () => {
+    const sibling_container = makeRectElement({
+      text: "sibling-container",
+      x: 10, y: 30, w: 80, h: 45,
+    }, false, true);
+
+    const child_a = makeRectElement({ text: "c1", x: 15, y: 35, w: 70, h: 15 }, true)
+    const child_b = makeRectElement({ text: "c2", x: 15, y: 55, w: 70, h: 15 }, true)
+
+    sibling_container.appendChild(child_a);
+    sibling_container.appendChild(child_b);
+
+    const ref = makeRectElement(
+      { text: "reference", x: 100, height: 100 }, true
+    );
+
+    const found = ref.findSpacnavElement(Math.PI);
+
+    expect(found).not.toBe(null);
+    expect(found.textContent.startsWith("c")).toBe(true);
+    expect(sibling_container.contains(found)).toBe(true);
+
+    expect(
+      child_a.findSpacnavElement(-2*Math.PI/3)
+    ).toBeFalsy();
+
+    expect(
+      child_a.findSpacnavElement(0)
+    ).toBe(ref);
+  });
+});

package/vitest.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+import { playwright   } from "@vitest/browser-playwright";
+
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      headless: true,
+      screenshotFailures: false,
+      provider: playwright(),
+      instances: [ { browser: "chromium" } ],
+    },
+  },
+});
+