fix: focus trap single tab stop

Author: segunadebayo

.changeset/focus-trap-single-tab-stop.md

@@ -0,0 +1,7 @@
+---
+"@zag-js/dom-query": patch
+"@zag-js/focus-trap": patch
+---
+
+- Fix focus trapping when the content has a single effective tab stop, such as a native radio group.
+- Handle disconnected `initialFocus` nodes more safely.

e2e/popover.e2e.ts

@@ -1,4 +1,4 @@
-import { test } from "@playwright/test"
+import { expect, test } from "@playwright/test"
 import { PopoverModel } from "./models/popover.model"
 
 let I: PopoverModel
@@ -55,6 +55,25 @@ test.describe("popover", () => {
     await I.seeLinkIsFocused()
   })
 
+  test("[keyboard / modal] should trap focus when content has a single effective tab stop", async ({ page }) => {
+    await page.goto("/popover/single-tab-stop")
+
+    const trigger = page.getByTestId("popover-trigger")
+    const checkedRadio = page.getByTestId("radio-name-asc")
+
+    await trigger.focus()
+    await expect(trigger).toBeFocused()
+
+    await page.keyboard.press("Enter")
+    await expect(checkedRadio).toBeFocused()
+
+    await page.keyboard.press("Tab")
+    await expect(checkedRadio).toBeFocused()
+
+    await page.keyboard.press("Shift+Tab")
+    await expect(checkedRadio).toBeFocused()
+  })
+
   test("[keyboard / non-modal] on tab outside: should move focus to next tabbable element after button", async () => {
     await I.focusTrigger()
     await I.seeTriggerIsFocused()

examples/next-ts/pages/popover/single-tab-stop.tsx

@@ -0,0 +1,46 @@
+import * as popover from "@zag-js/popover"
+import { normalizeProps, Portal, useMachine } from "@zag-js/react"
+import { useId } from "react"
+import { Presence } from "../../components/presence"
+
+export default function Page() {
+  const service = useMachine(popover.machine, {
+    id: useId(),
+    modal: true,
+  })
+
+  const api = popover.connect(service, normalizeProps)
+
+  return (
+    <main className="popover">
+      <div data-part="root">
+        <button data-testid="button-before">Button :before</button>
+
+        <button data-testid="popover-trigger" {...api.getTriggerProps()}>
+          Sort by
+        </button>
+
+        <Portal>
+          <div {...api.getPositionerProps()}>
+            <Presence data-testid="popover-content" className="popover-content" {...api.getContentProps()}>
+              <fieldset style={{ border: "none", padding: 0 }}>
+                <label>
+                  <input data-testid="radio-name-asc" type="radio" name="sort" value="name-asc" defaultChecked /> Name
+                  (A to Z)
+                </label>
+                <label>
+                  <input data-testid="radio-name-desc" type="radio" name="sort" value="name-desc" /> Name (Z to A)
+                </label>
+                <label>
+                  <input data-testid="radio-hours" type="radio" name="sort" value="hours" /> Hours
+                </label>
+              </fieldset>
+            </Presence>
+          </div>
+        </Portal>
+
+        <button data-testid="button-after">Button :after</button>
+      </div>
+    </main>
+  )
+}

packages/utilities/dom-query/src/tabbable.ts

@@ -1,4 +1,4 @@
-import { getActiveElement, isEditableElement, isElementVisible, isHTMLElement } from "./node"
+import { getActiveElement, isEditableElement, isElementVisible, isHTMLElement, isInputElement } from "./node"
 
 type IncludeContainerType = boolean | "if-empty"
 export type GetShadowRootOption = boolean | ((node: HTMLElement) => ShadowRoot | boolean | undefined) | undefined
@@ -26,6 +26,26 @@ function parseTabIndex(el: Element): number {
 const hasTabIndex = (el: Element) => !Number.isNaN(parseTabIndex(el))
 const hasNegativeTabIndex = (el: Element) => parseTabIndex(el) < 0
 
+function isRadioInput(element: HTMLElement): element is HTMLInputElement {
+  return isInputElement(element) && element.type === "radio"
+}
+
+function isTabbableRadio(element: HTMLElement): boolean {
+  if (!isRadioInput(element) || !element.name) return true
+  if (element.checked) return true
+
+  const selector = `input[type="radio"][name="${CSS.escape(element.name)}"]`
+  const scope = element.form ?? element.ownerDocument
+  const group = Array.from(scope.querySelectorAll<HTMLInputElement>(selector)).filter(
+    (radio) => radio.form === element.form && isFocusable(radio),
+  )
+
+  const checked = group.find((radio) => radio.checked)
+  if (checked) return checked === element
+
+  return group[0] === element
+}
+
 /**
  * Helper function to get the shadow root from an element based on the getShadowRoot option
  */
@@ -191,7 +211,8 @@ export function getTabbables(container: HTMLElement | null, options: TabbableOpt
 
 export function isTabbable(el: HTMLElement | EventTarget | null): el is HTMLElement {
   if (isHTMLElement(el) && el.tabIndex > 0) return true
-  return isFocusable(el) && !hasNegativeTabIndex(el)
+  if (!isFocusable(el) || hasNegativeTabIndex(el)) return false
+  return isTabbableRadio(el)
 }
 
 export function getFirstTabbable(container: HTMLElement | null, options: TabbableOptions = {}): HTMLElement | null {

packages/utilities/focus-trap/package.json

@@ -19,6 +19,7 @@
   "scripts": {
     "build": "tsup",
     "lint": "eslint src",
+    "test": "vitest --config ../../../vite.config.ts --environment jsdom --run tests",
     "typecheck": "tsc --noEmit",
     "prepack": "clean-package",
     "postpack": "clean-package restore"

packages/utilities/focus-trap/src/focus-trap.ts

@@ -537,6 +537,10 @@ export class FocusTrap {
       node = this.getNodeForOption("fallbackFocus")
     }
 
+    if (!node || !node.isConnected) {
+      throw new Error("Your focus-trap needs to have at least one focusable element")
+    }
+
     return node
   }