gpui: Add `focus_trap` to group the tab focus #34804

huacnlee · 2025-07-21T09:29:02Z

Continue #33008 to add a focus_trap option method for let tabs with in group.

This is used to help us to manage the focus loop when in some case like Modal, Popover.

Screen.Recording.2025-07-28.at.11.56.07.mov

Release Notes:

N/A

huacnlee · 2025-07-21T10:24:51Z

Ready for review

huacnlee · 2025-07-21T11:05:23Z

Maybe div().tab_group() can be use div().occlude() to avoid add a new API, but if true we need to rename HitboxBehavior::BlockMouse to HitboxBehavior::Block (Or add a new one).

zed/crates/gpui/src/elements/div.rs

Lines 970 to 973 in 57ab09c

fn occlude(mut self) -> Self {

self.interactivity().occlude_mouse();

self

}

zed/crates/gpui/src/window.rs

Lines 573 to 594 in 57ab09c

/// All hitboxes behind this hitbox will be ignored and so will have `hitbox.is_hovered() ==

/// false` and `hitbox.should_handle_scroll() == false`. Typically for elements this causes

/// skipping of all mouse events, hover styles, and tooltips. This flag is set by

/// [`InteractiveElement::occlude`].

///

/// For mouse handlers that check those hitboxes, this behaves the same as registering a

/// bubble-phase handler for every mouse event type:

///

/// ```

/// window.on_mouse_event(move |_: &EveryMouseEventTypeHere, phase, window, cx| {

/// if phase == DispatchPhase::Capture && hitbox.is_hovered(window) {

/// cx.stop_propagation();

/// }

/// }

/// ```

///

/// This has effects beyond event handling - any use of hitbox checking, such as hover

/// styles and tooltops. These other behaviors are the main point of this mechanism. An

/// alternative might be to not affect mouse event handling - but this would allow

/// inconsistent UI where clicks and moves interact with elements that are not considered to

/// be hovered.

BlockMouse,

After a moment think, I think split name is better, because occlude will happen in some case but that we not want to block tab focus.

huacnlee · 2025-07-21T11:16:43Z

Use for GPUI Component example:

longbridge/gpui-component#991

Screen.Recording.2025-07-22.at.19.08.25.mov

tidely

Looking pretty good, just some tiny nits that keep the code clear

crates/gpui/src/tab_stop.rs

tidely · 2025-07-21T14:16:14Z

crates/gpui/src/tab_stop.rs

-            prev_ix = self.handles.len().saturating_sub(1);
+            prev_ix = group_handles.len().saturating_sub(1);
        } else {
            prev_ix = ix.saturating_sub(1);


We check that ix is larger than 0 before, so this doesn't need to be saturating

No, even the ix is 0, the group_handles.len() may also 0.

I should’ve been more clear with what line I meant, that’s my bad. I think it only applies to prev_ix = ix.saturating_sub(1); since we know ix isn’t zero

crates/gpui/src/tab_stop.rs

Co-authored-by: tidely <[email protected]>

mikayla-maki · 2025-07-25T15:27:51Z

crates/gpui/src/window.rs


+    /// Set the tab group of this focus handle.
+    ///
+    /// If set, the focus cycle will loop in same group.


I don't think we want focus to cycle when hitting the edge of a tab group. Rather, I think it would make more sense if focus continued on to the next tab stop after the group.

Sorry, should you please explain more?
I am not got your point.

In this UI:

<tab-index = 0>  <tab-group tab-index = 1> <tab-index = 3> <tab-index = 2>  </tab-group> <tab-index = 2>

Calling focus_next repeatedly should result in an order like 0->2->3->1->0..., not 0->2->3->2->3->2->3...

Thanks, I see.

huacnlee · 2025-07-28T03:43:56Z

@mikayla-maki Let me explain the meaning of this feature:

The original intention is to add restrictions to tab focus for Modal and Popup scenarios, so that when Popup or Modal is opened, the tab focus always remains within the scope of the Modal, and is restored to other places after closing.

Screen.Recording.2025-07-28.at.11.56.07.mov

There is no such feature in HTML, but front-end components often implement it, and they use focus trap, such as:

Headless UI:
- https://headlessui.com/react/dialog#managing-initial-focus
- https://github.com/tailwindlabs/headlessui/blob/51b5bf646f6ec261ef81fb19c70bbabc6291a054/packages/%40headlessui-react/src/components/dialog/dialog.tsx#L323

Similar to Chrome:
https://github.com/user-attachments/assets/ab80ba44-89d5-42ce-a38f-2bdbbbf4d1aa

So, what if I rename this method to focus_trap?

…s also in the trap group.

This change adds the current tab index functionality to buttons and implements a proof of concept for the new welcome page. Primarily blocked on #34804, secondarily on #35075 so we can ensure navigation always works as intended. Another thing to consider here is whether we want to assign the tab order more implicitly / "automatically" based on the current layout ordering. This would generally enable us to add a default order to focusable elements if we want this. See [the specification](https://html.spec.whatwg.org/multipage/interaction.html#flattened-tabindex-ordered-focus-navigation-scope) on some more context on how the web usually handles this for focusable elements. Release Notes: - N/A

This change adds the current tab index functionality to buttons and implements a proof of concept for the new welcome page. Primarily blocked on zed-industries#34804, secondarily on zed-industries#35075 so we can ensure navigation always works as intended. Another thing to consider here is whether we want to assign the tab order more implicitly / "automatically" based on the current layout ordering. This would generally enable us to add a default order to focusable elements if we want this. See [the specification](https://html.spec.whatwg.org/multipage/interaction.html#flattened-tabindex-ordered-focus-navigation-scope) on some more context on how the web usually handles this for focusable elements. Release Notes: - N/A

huacnlee · 2025-09-25T16:36:12Z

#38531 is merged.

Wait zed-industries/zed#33008, zed-industries/zed#34804 to merge. https://github.com/user-attachments/assets/3c21ebc9-44a0-4311-bb0f-5f63fe8d4bb3 - Improved `focus_ring` to render like an outline. - Added to support press `Enter`, `Space` key to trigger Checkbox, Button, Radio. ## Break Changes - The `FocusableExt` has been changed to only for crate internal. - The `FocusableCycle` has been removed, now GPUI has it own tab stop implementation.

cla-bot bot added the cla-signed The user has signed the Contributor License Agreement label Jul 21, 2025

huacnlee changed the title ~~gpui: Add to support group the tab cycle~~ gpui: Add tab_group to group the tab focus Jul 21, 2025

This comment was marked as resolved.

Sign in to view

huacnlee mentioned this pull request Jul 21, 2025

chore: Refactor tab key to switch focus. longbridge/gpui-component#991

Merged

tidely reviewed Jul 21, 2025

View reviewed changes

huacnlee force-pushed the focus-trap branch 2 times, most recently from ed0ec39 to b361b4a Compare July 22, 2025 02:13

tidely reviewed Jul 22, 2025

View reviewed changes

crates/gpui/src/tab_stop.rs Outdated Show resolved Hide resolved

tidely reviewed Jul 22, 2025

View reviewed changes

crates/gpui/src/tab_stop.rs Outdated Show resolved Hide resolved

huacnlee and others added 13 commits July 22, 2025 18:26

gpui: Add to support group the tab cycle.

278dce6

.

20dc655

.

8d64d90

.

3f019a5

use global_id for tab_group.

5477a6f

better tab_group

ca95da3

.

cacf370

Improve example

e200e1f

Update example for let buttons in a group.

a1512f5

Update tab_stop code style.

be049dc

code style

473e97c

Update crates/gpui/src/tab_stop.rs

c740e1b

Co-authored-by: tidely <[email protected]>

code style

f3da55a

huacnlee force-pushed the focus-trap branch from ccf58cf to f3da55a Compare July 22, 2025 10:26

probably-neb assigned mikayla-maki Jul 23, 2025

mikayla-maki requested changes Jul 25, 2025

View reviewed changes

Rename tab_grop to focus_trap.

62ffba3

huacnlee changed the title ~~gpui: Add tab_group to group the tab focus~~ gpui: Add focus_trap to group the tab focus Jul 28, 2025

huacnlee added 5 commits July 28, 2025 13:34

.

f98a833

Merge branch 'main' into focus-trap

ac40c5c

Use window.use_state for modal state.

d6ce3df

Make sure the focus_handle of the current element of the focus trap i…

caf7880

…s also in the trap group.

.

aa3f617

huacnlee requested a review from mikayla-maki July 30, 2025 06:50

MrSubidubi mentioned this pull request Jul 30, 2025

ui: Wire up tab indices within buttons #35368

Merged

Merge branch 'main' into focus-trap

43c1b4d

Merge branch 'main' into focus-trap

1aa24fe

huacnlee closed this Sep 25, 2025

gpui: Add focus_trap to group the tab focus #34804

gpui: Add focus_trap to group the tab focus #34804

Uh oh!

Conversation

huacnlee commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

huacnlee commented Jul 21, 2025

Uh oh!

This comment was marked as resolved.

huacnlee commented Jul 21, 2025

Uh oh!

huacnlee commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tidely left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tidely Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

huacnlee Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

tidely Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikayla-maki Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

huacnlee Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

mikayla-maki Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huacnlee Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

huacnlee commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

huacnlee commented Sep 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gpui: Add `focus_trap` to group the tab focus #34804

gpui: Add `focus_trap` to group the tab focus #34804

huacnlee commented Jul 21, 2025 •

edited

Loading

huacnlee commented Jul 21, 2025 •

edited

Loading

mikayla-maki Jul 25, 2025 •

edited

Loading

huacnlee commented Jul 28, 2025 •

edited

Loading