@jsenv/dom 0.1.0

package/src/interaction/focus/element_is_visible.js

@@ -0,0 +1,36 @@
+import { getStyle } from "../../style/dom_styles.js";
+import {
+  elementIsDetails,
+  elementIsSummary,
+  isDocumentElement,
+} from "../../utils.js";
+
+export const elementIsVisible = (node) => {
+  if (isDocumentElement(node)) {
+    return true;
+  }
+  if (getStyle(node, "visibility") === "hidden") {
+    return false;
+  }
+  let nodeOrAncestor = node;
+  while (nodeOrAncestor) {
+    if (isDocumentElement(nodeOrAncestor)) {
+      break;
+    }
+    if (getStyle(nodeOrAncestor, "display") === "none") {
+      return false;
+    }
+    // Check if element is inside a closed details element
+    if (elementIsDetails(nodeOrAncestor) && !nodeOrAncestor.open) {
+      // Special case: summary elements are visible even when their parent details is closed
+      // But only if this details element is the direct parent of the summary
+      if (elementIsSummary(node) && node.parentElement === nodeOrAncestor) {
+        // Continue checking ancestors, don't return false yet
+      } else {
+        return false;
+      }
+    }
+    nodeOrAncestor = nodeOrAncestor.parentNode;
+  }
+  return true;
+};

package/src/interaction/focus/find_focusable.js

@@ -0,0 +1,21 @@
+import { findDescendant } from "../../traversal.js";
+import { getAssociatedElements } from "../../utils.js";
+import { elementIsFocusable } from "./element_is_focusable.js";
+
+export const findFocusable = (element) => {
+  const associatedElements = getAssociatedElements(element);
+  if (associatedElements) {
+    for (const associatedElement of associatedElements) {
+      const focusable = findFocusable(associatedElement);
+      if (focusable) {
+        return focusable;
+      }
+    }
+    return null;
+  }
+  if (elementIsFocusable(element)) {
+    return element;
+  }
+  const focusableDescendant = findDescendant(element, elementIsFocusable);
+  return focusableDescendant;
+};

package/src/interaction/focus/focus_group.js

@@ -0,0 +1,91 @@
+/**
+ * 
+- https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/Focusgroup/explainer.md
+ - https://open-ui.org/components/focusgroup.explainer/
+ - https://github.com/openui/open-ui/issues/990
+
+ - https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/Focusgroup/explainer.md#69-grid-focusgroups
+ */
+
+import { performArrowNavigation } from "./arrow_navigation.js";
+import { setFocusGroup } from "./focus_group_registry.js";
+import { isFocusNavMarked } from "./focus_nav_event_marker.js";
+import { performTabNavigation } from "./tab_navigation.js";
+
+export const initFocusGroup = (
+  element,
+  {
+    direction = "both",
+    // extend = true,
+    skipTab = true,
+    loop = false,
+    name, // Can be undefined for implicit ancestor-descendant grouping
+  } = {},
+) => {
+  const cleanupCallbackSet = new Set();
+  const cleanup = () => {
+    for (const callback of cleanupCallbackSet) {
+      callback();
+    }
+    cleanupCallbackSet.clear();
+  };
+
+  // Store focus group data in registry
+  const removeFocusGroup = setFocusGroup(element, {
+    direction,
+    loop,
+    name, // Store undefined as-is for implicit grouping
+  });
+  cleanupCallbackSet.add(removeFocusGroup);
+
+  tab: {
+    if (!skipTab) {
+      break tab;
+    }
+    const handleTabKeyDown = (event) => {
+      if (isFocusNavMarked(event)) {
+        // Prevent double handling of the same event + allow preventing focus nav from outside
+        return;
+      }
+      performTabNavigation(event, { outsideOfElement: element });
+    };
+    // Handle Tab navigation (exit group)
+    element.addEventListener("keydown", handleTabKeyDown, {
+      // we must use capture: false to let chance for other part of the code
+      // to call preventFocusNav
+      capture: false,
+      passive: false,
+    });
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener("keydown", handleTabKeyDown, {
+        capture: false,
+        passive: false,
+      });
+    });
+  }
+
+  // Handle Arrow key navigation (within group)
+  arrow_keys: {
+    const handleArrowKeyDown = (event) => {
+      if (isFocusNavMarked(event)) {
+        // Prevent double handling of the same event + allow preventing focus nav from outside
+        return;
+      }
+      performArrowNavigation(event, element, { direction, loop, name });
+    };
+    element.addEventListener("keydown", handleArrowKeyDown, {
+      // we must use capture: false to let chance for other part of the code
+      // to call preventFocusNav
+      capture: false,
+      passive: false,
+    });
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener("keydown", handleArrowKeyDown, {
+        capture: false,
+        passive: false,
+      });
+    });
+  }
+
+  return { cleanup };
+};

package/src/interaction/focus/focus_group_registry.js

@@ -0,0 +1,12 @@
+// WeakMap to store focus group metadata
+export const focusGroupRegistry = new WeakMap();
+
+export const setFocusGroup = (element, options) => {
+  focusGroupRegistry.set(element, options);
+  return () => {
+    focusGroupRegistry.delete(element);
+  };
+};
+export const getFocusGroup = (element) => {
+  return focusGroupRegistry.get(element);
+};

package/src/interaction/focus/focus_nav.js

@@ -0,0 +1,12 @@
+import { preventFocusNav } from "./focus_nav_event_marker.js";
+
+export const preventFocusNavViaKeyboard = (keyboardEvent) => {
+  if (keyboardEvent.key === "Tab") {
+    // prevent tab to move focus
+    keyboardEvent.preventDefault();
+    return true;
+  }
+  // ensure we won't perform our internal focus nav in focus groups
+  preventFocusNav(keyboardEvent);
+  return false;
+};

package/src/interaction/focus/focus_nav_event_marker.js

@@ -0,0 +1,14 @@
+import { createEventMarker } from "../event_marker.js";
+
+export const focusNavEventMarker = createEventMarker("focus_nav");
+
+export const preventFocusNav = (event) => {
+  focusNavEventMarker.mark(event);
+};
+
+export const isFocusNavMarked = (event) => {
+  return focusNavEventMarker.isMarked(event);
+};
+export const markFocusNav = (event) => {
+  focusNavEventMarker.mark(event);
+};

package/src/interaction/focus/focus_trap.js

@@ -0,0 +1,105 @@
+import { performTabNavigation } from "./tab_navigation.js";
+
+export const trapFocusInside = (element) => {
+  if (element.nodeType === 3) {
+    console.warn("cannot trap focus inside a text node");
+    return () => {};
+  }
+
+  const trappedElement = activeTraps.find(
+    (activeTrap) => activeTrap.element === element,
+  );
+  if (trappedElement) {
+    console.warn("focus already trapped inside this element");
+    return () => {};
+  }
+
+  const isEventOutside = (event) => {
+    if (event.target === element) return false;
+    if (element.contains(event.target)) return false;
+    return true;
+  };
+
+  const lock = () => {
+    const onmousedown = (event) => {
+      if (isEventOutside(event)) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+      }
+    };
+
+    const onkeydown = (event) => {
+      if (isTabEvent(event)) {
+        performTabNavigation(event, { rootElement: element });
+      }
+    };
+
+    document.addEventListener("mousedown", onmousedown, {
+      capture: true,
+      passive: false,
+    });
+    document.addEventListener("keydown", onkeydown, {
+      capture: true,
+      passive: false,
+    });
+
+    return () => {
+      document.removeEventListener("mousedown", onmousedown, {
+        capture: true,
+        passive: false,
+      });
+      document.removeEventListener("keydown", onkeydown, {
+        capture: true,
+        passive: false,
+      });
+    };
+  };
+
+  const deactivate = activate({
+    // element
+    lock,
+  });
+
+  const untrap = () => {
+    deactivate();
+  };
+
+  return untrap;
+};
+
+const isTabEvent = (event) => event.key === "Tab" || event.keyCode === 9;
+
+const activeTraps = [];
+const activate = ({ lock }) => {
+  // unlock any trap currently activated
+  let previousTrap;
+  if (activeTraps.length > 0) {
+    previousTrap = activeTraps[activeTraps.length - 1];
+    previousTrap.unlock();
+  }
+
+  // store trap methods to lock/unlock as traps are acivated/deactivated
+  const trap = { lock, unlock: lock() };
+  activeTraps.push(trap);
+
+  return () => {
+    if (activeTraps.length === 0) {
+      console.warn("cannot deactivate an already deactivated trap");
+      return;
+    }
+    const lastTrap = activeTraps[activeTraps.length - 1];
+    if (trap !== lastTrap) {
+      // TODO: investigate this and maybe remove this requirment
+      console.warn(
+        "you must deactivate trap in the same order they were activated",
+      );
+      return;
+    }
+    activeTraps.pop();
+    trap.unlock();
+    // if any,reactivate the previous trap
+    if (previousTrap) {
+      previousTrap.unlock = previousTrap.lock();
+    }
+  };
+};

package/src/interaction/focus/tab_navigation.js

@@ -0,0 +1,128 @@
+import {
+  findAfter,
+  findBefore,
+  findDescendant,
+  findLastDescendant,
+} from "../../traversal.js";
+import { elementIsFocusable } from "./element_is_focusable.js";
+import { markFocusNav } from "./focus_nav_event_marker.js";
+
+const DEBUG = true;
+
+export const performTabNavigation = (
+  event,
+  { rootElement = document.body, outsideOfElement = null } = {},
+) => {
+  if (!isTabEvent(event)) {
+    return false;
+  }
+  const activeElement = document.activeElement;
+  if (activeElement.getAttribute("data-focusnav") === "none") {
+    event.preventDefault(); // ensure tab cannot move focus
+    return true;
+  }
+  const isForward = !event.shiftKey;
+  const onTargetToFocus = (targetToFocus) => {
+    console.debug(
+      `Tab navigation: ${isForward ? "forward" : "backward"} from`,
+      activeElement,
+      "to",
+      targetToFocus,
+    );
+    event.preventDefault();
+    markFocusNav(event);
+    targetToFocus.focus();
+  };
+
+  if (DEBUG) {
+    console.debug(
+      `Tab navigation: ${isForward ? "forward" : "backward"} from,`,
+      activeElement,
+    );
+  }
+
+  const predicate = (candidate) => {
+    const canBeFocusedByTab = isFocusableByTab(candidate);
+    if (DEBUG) {
+      console.debug(`Testing`, candidate, `${canBeFocusedByTab ? "✓" : "✗"}`);
+    }
+    return canBeFocusedByTab;
+  };
+
+  const activeElementIsRoot = activeElement === rootElement;
+  forward: {
+    if (!isForward) {
+      break forward;
+    }
+    if (activeElementIsRoot) {
+      const firstFocusableElement = findDescendant(activeElement, predicate, {
+        skipRoot: outsideOfElement,
+      });
+      if (firstFocusableElement) {
+        return onTargetToFocus(firstFocusableElement);
+      }
+      return false;
+    }
+    const nextFocusableElement = findAfter(activeElement, predicate, {
+      root: rootElement,
+      skipRoot: outsideOfElement,
+    });
+    if (nextFocusableElement) {
+      return onTargetToFocus(nextFocusableElement);
+    }
+    const firstFocusableElement = findDescendant(activeElement, predicate, {
+      skipRoot: outsideOfElement,
+    });
+    if (firstFocusableElement) {
+      return onTargetToFocus(firstFocusableElement);
+    }
+    return false;
+  }
+
+  backward: {
+    if (activeElementIsRoot) {
+      const lastFocusableElement = findLastDescendant(
+        activeElement,
+        predicate,
+        {
+          skipRoot: outsideOfElement,
+        },
+      );
+      if (lastFocusableElement) {
+        return onTargetToFocus(lastFocusableElement);
+      }
+      return false;
+    }
+
+    const previousFocusableElement = findBefore(activeElement, predicate, {
+      root: rootElement,
+      skipRoot: outsideOfElement,
+    });
+    if (previousFocusableElement) {
+      return onTargetToFocus(previousFocusableElement);
+    }
+    const lastFocusableElement = findLastDescendant(activeElement, predicate, {
+      skipRoot: outsideOfElement,
+    });
+    if (lastFocusableElement) {
+      return onTargetToFocus(lastFocusableElement);
+    }
+    return false;
+  }
+};
+
+export const isTabEvent = (event) => event.key === "Tab" || event.keyCode === 9;
+
+const isFocusableByTab = (element) => {
+  if (hasNegativeTabIndex(element)) {
+    return false;
+  }
+  return elementIsFocusable(element);
+};
+const hasNegativeTabIndex = (element) => {
+  return (
+    element.hasAttribute &&
+    element.hasAttribute("tabIndex") &&
+    Number(element.getAttribute("tabindex")) < 0
+  );
+};

package/src/interaction/focus/tests/focus_group_skip_tab_test.html

@@ -0,0 +1,206 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Focus Group Test - Skip Tab</title>
+    <style>
+      body {
+        font-family:
+          system-ui,
+          -apple-system,
+          sans-serif;
+        margin: 40px;
+        line-height: 1.6;
+      }
+
+      .test-section {
+        margin: 30px 0;
+        padding: 20px;
+        border: 2px solid #e0e0e0;
+        border-radius: 8px;
+      }
+
+      .focus-group {
+        background: #f5f5f5;
+        border: 2px dashed #999;
+        padding: 15px;
+        margin: 10px 0;
+        border-radius: 4px;
+      }
+
+      .focus-group h3 {
+        margin-top: 0;
+        color: #666;
+      }
+
+      button,
+      input,
+      select,
+      textarea {
+        margin: 5px;
+        padding: 8px 12px;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        font-size: 14px;
+      }
+
+      button:focus,
+      input:focus,
+      select:focus,
+      textarea:focus {
+        outline: 2px solid #007acc;
+        outline-offset: 2px;
+      }
+
+      .instructions {
+        background: #e8f4fd;
+        padding: 15px;
+        border-radius: 4px;
+        margin-bottom: 20px;
+      }
+
+      .status {
+        position: fixed;
+        top: 10px;
+        right: 10px;
+        background: #333;
+        color: white;
+        padding: 10px;
+        border-radius: 4px;
+        font-family: monospace;
+        font-size: 12px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="status" id="status">Focus: none</div>
+
+    <h1>Focus Group Test - Skip Tab</h1>
+
+    <div class="instructions">
+      <strong>Test Instructions:</strong>
+      <ol>
+        <li>Use <kbd>Tab</kbd> to navigate through focusable elements</li>
+        <li>
+          Elements in the focus group are still accessible (click them or
+          navigate normally)
+        </li>
+        <li>
+          When you're focused on an element INSIDE the focus group and press
+          <kbd>Tab</kbd>, it should jump to the next focusable element OUTSIDE
+          the group
+        </li>
+        <li>
+          Elements before and after the focus group should have normal tab
+          behavior
+        </li>
+        <li>
+          Try clicking on elements inside the focus group, then pressing
+          <kbd>Tab</kbd>
+        </li>
+      </ol>
+    </div>
+
+    <div class="test-section">
+      <h2>Before Focus Group</h2>
+      <button>Button Before 1</button>
+      <input type="text" placeholder="Input Before 1" />
+      <button>Button Before 2</button>
+    </div>
+
+    <div class="test-section">
+      <h2>Focus Group (skipTab = true)</h2>
+      <div class="focus-group" id="focus-group-1">
+        <h3>� Tab from inside this group jumps outside</h3>
+        <button>Button in Group 1</button>
+        <input type="text" placeholder="Input in Group 1" />
+        <select>
+          <option>Option 1</option>
+          <option>Option 2</option>
+        </select>
+        <button>Button in Group 2</button>
+        <textarea placeholder="Textarea in Group"></textarea>
+        <button>Button in Group 3</button>
+      </div>
+    </div>
+
+    <div class="test-section">
+      <h2>After Focus Group</h2>
+      <button>Button After 1</button>
+      <input type="text" placeholder="Input After 1" />
+      <button>Button After 2</button>
+    </div>
+
+    <div class="test-section">
+      <h2>Control Group (no focus group)</h2>
+      <div class="focus-group" style="border-color: #4caf50">
+        <h3>✅ This group has normal tab behavior</h3>
+        <button>Normal Button 1</button>
+        <input type="text" placeholder="Normal Input 1" />
+        <button>Normal Button 2</button>
+      </div>
+    </div>
+
+    <script type="module">
+      import { initFocusGroup } from "../focus_group.js";
+
+      // Initialize the focus group with skipTab enabled
+      const focusGroup = document.getElementById("focus-group-1");
+      initFocusGroup(focusGroup, {
+        skipTab: true,
+      });
+
+      // Status tracking for debugging
+      const statusEl = document.getElementById("status");
+
+      function updateStatus() {
+        const activeElement = document.activeElement;
+        const tagName = activeElement.tagName.toLowerCase();
+        const text =
+          activeElement.textContent ||
+          activeElement.placeholder ||
+          activeElement.value ||
+          "";
+        const truncatedText =
+          text.length > 20 ? `${text.substring(0, 20)}...` : text;
+
+        statusEl.textContent = `Focus: ${tagName}${truncatedText ? ` (${truncatedText})` : ""}`;
+      }
+
+      // Track focus changes
+      document.addEventListener("focusin", updateStatus);
+      document.addEventListener("focusout", updateStatus);
+
+      // Initial status
+      updateStatus();
+
+      // Add some debugging
+      focusGroup.addEventListener(
+        "keydown",
+        (e) => {
+          if (e.key === "Tab") {
+            console.log("Tab pressed in focus group", {
+              target: e.target,
+              shiftKey: e.shiftKey,
+              defaultPrevented: e.defaultPrevented,
+            });
+          }
+        },
+        { capture: true },
+      );
+
+      // Log tab events globally for debugging
+      document.addEventListener("keydown", (e) => {
+        if (e.key === "Tab") {
+          console.log("Global tab event:", {
+            target: e.target,
+            shiftKey: e.shiftKey,
+            defaultPrevented: e.defaultPrevented,
+            activeElement: document.activeElement,
+          });
+        }
+      });
+    </script>
+  </body>
+</html>