Skip to content

Lightpanda: the headless browser designed for AI and automation

webapi: run sequential focus navigation on Tab

Navid EMAD7c1af5762d7c
diff --git a/src/browser/Frame.zig b/src/browser/Frame.zig
index bbe669fc2..b446429ae 100644
--- a/src/browser/Frame.zig
+++ b/src/browser/Frame.zig
@@ -4167,7 +4167,11 @@ pub fn handleClick(self: *Frame, target: *Node) !void {
pub fn triggerKeyboard(self: *Frame, keyboard_event: *KeyboardEvent) !void {
const event = keyboard_event.asEvent();
- const element = self.window._document._active_element orelse {
+ // Dispatch to the effective active element. When nothing is explicitly
+ // focused this resolves to <body> (matching `document.activeElement`), so
+ // the keydown still fires and its default action — e.g. sequential focus
+ // navigation on Tab — can run.
+ const element = self.window._document.getActiveElement() orelse {
event.deinit(self._page);
return;
};
@@ -4191,6 +4195,12 @@ pub fn handleKeydown(self: *Frame, target: *Node, event: *Event) !void {
return;
}
+ if (key == .Tab) {
+ // Sequential focus navigation is the default action of a Tab keydown.
+ // Shift+Tab walks backward.
+ return self.moveFocus(if (keyboard_event.getShiftKey()) .backward else .forward);
+ }
+
if (target.is(Element.Html.Input)) |input| {
if (key == .Enter) {
return self.submitForm(input.asElement(), input.getForm(self), .{});
@@ -4221,6 +4231,93 @@ pub fn handleKeydown(self: *Frame, target: *Node, event: *Event) !void {
}
}
+const FocusDirection = enum { forward, backward };
+
+// Sequential focus navigation: move `document.activeElement` to the next (Tab)
+// or previous (Shift+Tab) focusable element, firing the usual blur/focus events
+// via `Element.focus`. The order is fully determined by tabindex + document
+// position, so no layout is needed:
+// 1. elements with a positive tabindex, in ascending tabindex order;
+// 2. then elements with tabindex 0 (or a natively-focusable default), in
+// document order.
+// Ties within a group break on document order, and Tab wraps around at the ends.
+// https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation
+fn moveFocus(self: *Frame, direction: FocusDirection) !void {
+ const document = self.document;
+ const current = document._active_element;
+ const forward = direction == .forward;
+
+ // Single document-order pass tracking two candidates:
+ // chosen — the closest focusable element strictly past `current` in the
+ // travel direction.
+ // edge — the global first (forward) / last (backward) focusable element,
+ // used to wrap around when `current` is at an end, or as the
+ // landing spot when nothing is focused yet.
+ var chosen: ?*Element = null;
+ var edge: ?*Element = null;
+
+ var tw = @import("webapi/TreeWalker.zig").Full.Elements.init(document.asNode(), .{});
+ while (tw.next()) |el| {
+ if (!sequentiallyFocusable(el)) continue;
+
+ if (edge == null or focusOrderBefore(el, edge.?) == forward) {
+ edge = el;
+ }
+
+ const cur = current orelse continue;
+ if (el == cur) continue;
+ const past = if (forward) focusOrderBefore(cur, el) else focusOrderBefore(el, cur);
+ if (!past) continue;
+ if (chosen == null or focusOrderBefore(el, chosen.?) == forward) {
+ chosen = el;
+ }
+ }
+
+ const next = chosen orelse edge orelse return;
+ try next.focus(self);
+}
+
+// True when `el` participates in sequential focus navigation: enabled, with a
+// non-negative tabindex, and either an explicit tabindex or a natively
+// focusable shape. `getTabIndex` defaults several tags to 0, including
+// href-less anchors and hidden inputs, so the structural conditions are
+// re-checked here.
+fn sequentiallyFocusable(el: *Element) bool {
+ const html_el = el.is(Element.Html) orelse return false;
+ if (el.isDisabled()) return false;
+ if (html_el.getTabIndex() < 0) return false;
+
+ if (el.getAttributeSafe(comptime .wrap("tabindex")) != null) return true;
+
+ return switch (el.getTag()) {
+ .button, .select, .textarea, .iframe => true,
+ .input => if (el.is(Element.Html.Input)) |input| input._input_type != .hidden else false,
+ .anchor, .area => el.getAttributeSafe(comptime .wrap("href")) != null,
+ else => false,
+ };
+}
+
+// Orders two focusable elements by sequential focus navigation order: positive
+// tabindex first (ascending), then tabindex 0, ties broken by document order.
+fn focusOrderBefore(a: *Element, b: *Element) bool {
+ const ta = tabOrderIndex(a);
+ const tb = tabOrderIndex(b);
+ if (ta != tb) {
+ const group_a: u8 = if (ta > 0) 0 else 1;
+ const group_b: u8 = if (tb > 0) 0 else 1;
+ if (group_a != group_b) return group_a < group_b;
+ return ta < tb;
+ }
+ // Equal tabindex → document order: `a` precedes `b` when `b` follows `a`.
+ const FOLLOWING: u16 = 0x04;
+ return (a.asNode().compareDocumentPosition(b.asNode()) & FOLLOWING) != 0;
+}
+
+fn tabOrderIndex(el: *Element) i32 {
+ const html_el = el.is(Element.Html) orelse return 0;
+ return html_el.getTabIndex();
+}
+
const SubmitFormOpts = struct {
fire_event: bool = true,
};
diff --git a/src/cdp/domains/input.zig b/src/cdp/domains/input.zig
index a6772abd3..a865ee344 100644
--- a/src/cdp/domains/input.zig
+++ b/src/cdp/domains/input.zig
@@ -314,3 +314,59 @@ test "cdp.input: dispatchMouseEvent right button fires contextmenu, double-click
const result = try ls.local.compileAndRun("window.downButton === 2 && window.ctxButton === 2 && window.dbl === true", null);
try testing.expect(result.isTrue());
}
+
+test "cdp.input: dispatchKeyEvent Tab runs sequential focus navigation" {
+ var ctx = try testing.context();
+ defer ctx.deinit();
+
+ const bc = try ctx.loadBrowserContext(.{});
+ const frame = try bc.session.createPage();
+ const url = "http://localhost:9582/src/browser/tests/mcp_actions.html";
+ try frame.navigate(url, .{ .reason = .address_bar, .kind = .{ .push = null } });
+ var runner = try bc.session.runner(.{});
+ try runner.wait(.{ .ms = 2000 });
+
+ var ls: lp.js.Local.Scope = undefined;
+ frame.js.localScope(&ls);
+ defer ls.deinit();
+
+ var try_catch: lp.js.TryCatch = undefined;
+ try_catch.init(&ls.local);
+ defer try_catch.deinit();
+
+ // Three controls whose tabindex order (1, 2, 3) differs from document
+ // order (2, 1, 3): focus order must follow tabindex, not the tree.
+ _ = try ls.local.compileAndRun(
+ \\document.body.innerHTML =
+ \\ '<input id="i2" tabindex="2">' +
+ \\ '<button id="b1" tabindex="1">b</button>' +
+ \\ '<select id="s3" tabindex="3"></select>';
+ , null);
+
+ // Nothing focused yet → activeElement is <body>.
+ try testing.expect((try ls.local.compileAndRun("document.activeElement === document.body", null)).isTrue());
+
+ // First Tab → lowest positive tabindex (#b1), regardless of document order.
+ try ctx.processMessage(.{
+ .id = 1,
+ .method = "Input.dispatchKeyEvent",
+ .params = .{ .type = "keyDown", .key = "Tab", .code = "Tab" },
+ });
+ try testing.expect((try ls.local.compileAndRun("document.activeElement.id === 'b1'", null)).isTrue());
+
+ // Second Tab → next in tabindex order (#i2).
+ try ctx.processMessage(.{
+ .id = 2,
+ .method = "Input.dispatchKeyEvent",
+ .params = .{ .type = "keyDown", .key = "Tab", .code = "Tab" },
+ });
+ try testing.expect((try ls.local.compileAndRun("document.activeElement.id === 'i2'", null)).isTrue());
+
+ // Shift+Tab (modifiers bit 8) walks backward → back to #b1.
+ try ctx.processMessage(.{
+ .id = 3,
+ .method = "Input.dispatchKeyEvent",
+ .params = .{ .type = "keyDown", .key = "Tab", .code = "Tab", .modifiers = 8 },
+ });
+ try testing.expect((try ls.local.compileAndRun("document.activeElement.id === 'b1'", null)).isTrue());
+}