Focus Trap

Requirements

• Export createFocusTrap(container) as named and default. container is a connected, visible HTMLElement. Return an idempotent cleanup function that removes the trap and restores the previously focused connected HTMLElement.
• Eligible descendants are enabled button/input/select/textarea elements, anchors with href, and elements with tabindex, provided tabIndex is nonnegative. Exclude hidden inputs, disabled controls, and elements under hidden or inert ancestors or ancestors with display:none or visibility:hidden/collapse. Use DOM order, including positive tabindex values; native positive-tabindex priority, radio groups, fieldset inheritance, shadow DOM, and iframes are outside scope.
• At setup, retain focus if it is already on an eligible descendant; otherwise focus the first eligible descendant. If none exists, focus the container. Add tabindex="-1" to the container only when it has no tabindex attribute, and restore its original attribute state on cleanup.
• Listen for document keydown. For unmodified Tab, wrap last to first; for Shift+Tab, wrap first to last. If focus is outside the eligible list, send forward Tab to first and backward Tab to last. Prevent default only when redirecting focus. Interior Tab events retain normal browser behavior.
• Recompute the eligible list on every Tab so added, removed, disabled, or hidden elements are handled. With no eligible descendants, prevent Tab and keep focus on the container. Ignore non-Tab, Ctrl/Alt/Meta+Tab, and already-prevented events.
• Cleanup must remove the listener and restore focus once, without creating or removing child elements. Assume one active trap per document; preventing mouse/programmatic escape, Escape-to-close, modal semantics, and production-complete tabbability are outside scope. Tests supply DOM fixtures; no HTML/CSS file is required.

Examples

Input: const cleanup = createFocusTrap(dialog); // dialog contains two buttons
// Press Tab on the last button.
Output: Focus moves to the first button and the Tab event is prevented.

Input: cleanup(); cleanup();
Output: The listener is removed and the prior connected element is focused only once.