@jsenv/dom 0.12.0 → 0.12.2

package/dist/jsenv_dom.js

@@ -4375,21 +4375,30 @@ const findFocusDelegateTarget = (el) => {
   return null;
 };
 
-const findFocusable = (element) => {
+const findFocusable = (element, { exclude } = {}) => {
   const associatedElements = getAssociatedElements(element);
   if (associatedElements) {
     for (const associatedElement of associatedElements) {
-      const focusable = findFocusable(associatedElement);
+      const focusable = findFocusable(associatedElement, { exclude });
       if (focusable) {
         return focusable;
       }
     }
     return null;
   }
-  if (elementIsFocusable(element)) {
+  const isFocusable = (node) => {
+    if (!elementIsFocusable(node)) {
+      return false;
+    }
+    if (exclude && exclude(node)) {
+      return false;
+    }
+    return true;
+  };
+  if (isFocusable(element)) {
     return element;
   }
-  const focusableDescendant = findDescendant(element, elementIsFocusable);
+  const focusableDescendant = findDescendant(element, isFocusable);
   if (focusableDescendant) {
     // If the first focusable is an unchecked radio/checkbox, prefer the checked
     // sibling in the same group (mirrors native browser radio focus behavior
@@ -4496,10 +4505,15 @@ const DEFAULT_BEHAVIORS = [
     keys: {
       // Tab moves focus on any element
       tab: "focus_nav",
-      // Escape dismisses on any element (dialog, search clear, dropdown close, etc.)
+    },
+    // no fallback: only claims Tab, other keys continue to next entries
+  },
+  {
+    // Escape natively dismisses only <dialog> elements
+    test: (el) => el.tagName === "DIALOG" || Boolean(el.closest("dialog")),
+    keys: {
       escape: "dismiss",
     },
-    // no fallback: only claims Tab/Escape, other keys continue to next entries
   },
   {
     test: (el) => el.matches("input[type='radio'], input[type='checkbox']"),
@@ -4518,6 +4532,12 @@ const DEFAULT_BEHAVIORS = [
         "input:not([type]), input[type='text'], input[type='search'], input[type='url'], input[type='email'], input[type='password'], input[type='tel']",
       ),
     keys: {
+      escape: (e) => {
+        if (e.target.type === "search") {
+          return e.target.value ? "clear" : "";
+        }
+        return "";
+      },
       enter: (e) => (e.target.form ? "form_submit" : ""),
       arrowleft: "cursor_move",
       arrowright: "cursor_move",
@@ -5427,10 +5447,36 @@ const performTabNavigation = (
     return elementIsFocusable(element, { excludeAriaHidden });
   };
 
-  const predicate = (candidate) => {
-    const canBeFocusedByTab = isFocusableByTab(candidate);
-    // debug(`Testing`, candidate, `${canBeFocusedByTab ? "✓" : "✗"}`);
-    return canBeFocusedByTab;
+  // A focus group "owns" the activeElement when activeElement is inside it.
+  // From the inside, Tab should exit the group (skip its remaining children).
+  // From the outside, Tab should enter the group normally (first focusable child).
+  const activeFocusGroup =
+    activeElement.closest?.("[navi-focus-group]") || null;
+  const isOwnedByActiveFocusGroup = (el) =>
+    activeFocusGroup && activeFocusGroup.contains(el);
+
+  const predicate = (candidate, skip) => {
+    if (!isFocusableByTab(candidate)) {
+      return false;
+    }
+    // Focus group roots are composite widgets.
+    if (candidate.hasAttribute("navi-focus-group")) {
+      if (isFocusableByTab(candidate)) {
+        // Root has tabindex="0": it is the single Tab stop for the group.
+        // Skip its children — arrow keys handle internal navigation.
+        skip?.();
+        return true;
+      }
+      // Root is not focusable by Tab: descend into children to allow Tab entry.
+      return false;
+    }
+    // If candidate is inside the focus group that currently owns focus, skip
+    // it — Tab should exit the group. (Going *into* a different focus group
+    // is allowed: only one focus group at a time has the activeElement.)
+    if (isOwnedByActiveFocusGroup(candidate)) {
+      return false;
+    }
+    return true;
   };
 
   const activeElementIsRoot = activeElement === rootElement;
@@ -5574,6 +5620,10 @@ const initFocusGroup = (
     name, // Store undefined as-is for implicit grouping
   });
   cleanupCallbackSet.add(removeFocusGroup);
+  element.setAttribute("navi-focus-group", "");
+  cleanupCallbackSet.add(() => {
+    element.removeAttribute("navi-focus-group");
+  });
 
   tab: {
     if (!skipTab) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/dom",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "type": "module",
   "description": "DOM utilities for writing frontend code",
   "repository": {