refactor

Cargo.lock

@@ -1703,6 +1703,7 @@ dependencies = [
  "gpui",
  "gpui-native-icons",
  "gpui-native-theme",
+ "gpui-native-utils",
  "unicode-segmentation",
 ]
 
@@ -1713,6 +1714,7 @@ dependencies = [
  "gpui",
  "gpui-native-icons",
  "gpui-native-theme",
+ "gpui-native-utils",
 ]
 
 [[package]]
@@ -1747,6 +1749,14 @@ dependencies = [
  "toml 0.8.23",
 ]
 
+[[package]]
+name = "gpui-native-utils"
+version = "0.1.0"
+dependencies = [
+ "gpui",
+ "gpui-native-theme",
+]
+
 [[package]]
 name = "gpui_apple"
 version = "0.1.0"

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/theme", "crates/icons", "crates/core", "crates/data", "examples/gallery"]
+members = ["crates/theme", "crates/utils", "crates/icons", "crates/core", "crates/data", "examples/gallery"]
 
 [package]
 name = "gpui-native-kit"
@@ -28,3 +28,4 @@ gpui-native-core = { path = "crates/core" }
 gpui-native-data = { path = "crates/data" }
 gpui-native-icons = { path = "crates/icons" }
 gpui-native-theme = { path = "crates/theme" }
+gpui-native-utils = { path = "crates/utils" }

crates/core/Cargo.toml

@@ -8,6 +8,7 @@ description = "The GPUI components every application needs, one cargo feature ea
 gpui = { workspace = true }
 gpui-native-icons = { workspace = true }
 gpui-native-theme = { workspace = true }
+gpui-native-utils = { workspace = true }
 unicode-segmentation = "1.12"
 
 [dev-dependencies]

crates/core/src/button.rs

@@ -2,12 +2,12 @@
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    AnyView, App, BoxShadow, ClickEvent, ElementId, InteractiveElement as _, IntoElement,
+    AnyView, App, ClickEvent, ElementId, InteractiveElement as _, IntoElement, ParentElement as _,
-    ParentElement as _, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
+    RenderOnce, Role, SharedString, StatefulInteractiveElement as _, Styled as _, Window, relative,
-    Styled as _, Window, px, relative,
 };
 use gpui_native_icons::{IconRole, icon};
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 use std::rc::Rc;
 
 use crate::common::{Sizable, h_flex};
@@ -193,11 +193,7 @@ impl RenderOnce for Button {
                     .tab_stop(true)
                     .hover(move |style| style.bg(hover))
                     .active(move |style| style.bg(pressed))
-                    .focus_visible(|style| {
+                    .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                        style.shadow(vec![
-                            BoxShadow::new(px(0.), px(0.), colors.ring).spread_radius(px(3.)),
-                        ])
-                    })
                     .when_some(on_click, |button, on_click| {
                         button.on_click(move |event, window, cx| on_click(event, window, cx))
                     })

crates/core/src/checkbox.rs

@@ -2,12 +2,12 @@
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    App, BoxShadow, ElementId, InteractiveElement as _, IntoElement, ParentElement as _,
+    App, ElementId, InteractiveElement as _, IntoElement, ParentElement as _, RenderOnce, Role,
-    RenderOnce, Role, SharedString, StatefulInteractiveElement as _, Styled as _, Toggled, Window,
+    SharedString, StatefulInteractiveElement as _, Styled as _, Toggled, Window,
-    px,
 };
 use gpui_native_icons::{IconRole, icon};
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 
 use crate::common::{Sizable, h_flex};
 
@@ -112,13 +112,7 @@ impl RenderOnce for Checkbox {
                     .cursor_pointer()
                     .focusable()
                     .tab_stop(true)
-                    .focus_visible(|style| {
+                    .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                        // Paint-only keyboard ring; the width joins the native
-                        // metrics table when that lands.
-                        style.shadow(vec![
-                            BoxShadow::new(px(0.), px(0.), colors.ring).spread_radius(px(3.)),
-                        ])
-                    })
                     .when_some(on_change, |checkbox, on_change| {
                         checkbox.on_click(move |_, window, cx| on_change(next, window, cx))
                     })

crates/core/src/common.rs

@@ -1,18 +1,7 @@
 //! Shared element constructors and small style helpers.
 
-use gpui::{Div, Styled as _, div};
-
 pub use gpui_native_theme::Size;
-
+pub use gpui_native_utils::{h_flex, v_flex};
-/// A row whose children center on the cross axis.
-pub fn h_flex() -> Div {
-    div().flex().flex_row().items_center()
-}
-
-/// A column whose children stretch across the cross axis.
-pub fn v_flex() -> Div {
-    div().flex().flex_col()
-}
 
 /// A component that can be told which size to render at.
 pub trait Sizable: Sized {

crates/core/src/dialog.rs

@@ -157,16 +157,15 @@ impl RenderOnce for Dialog {
         let alert = self.alert;
 
         // Keyboard focus rides the panel across frames.
-        let focus_handle = window.use_keyed_state("dialog-focus", cx, |_, cx| cx.focus_handle());
+        let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
 
         let content = self.content.map(|build| build(window, cx));
         let actions = self.actions.map(|build| build(window, cx));
-
         let panel_bounds: BoundsCell = Rc::new(RefCell::new(None));
 
         let panel = v_flex()
             .id("dialog-panel")
-            .track_focus(&focus_handle.read(cx).clone())
+            .track_focus(&focus)
             .role(role)
             .aria_label(label)
             .min_w_64()
@@ -214,11 +213,9 @@ impl RenderOnce for Dialog {
                         move |bounds, _window, _cx| *cell.borrow_mut() = Some(bounds)
                     },
                     {
-                        let focus_handle = focus_handle.clone();
                         move |_, _, window, cx| {
-                            let handle = focus_handle.read(cx).clone();
+                            if !focus.contains_focused(window, cx) {
-                            if !handle.contains_focused(window, cx) {
+                                window.focus(&focus, cx);
-                                window.focus(&handle, cx);
                             }
                         }
                     },

crates/core/src/link.rs

@@ -1,10 +1,10 @@
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    App, BoxShadow, ClickEvent, ElementId, InteractiveElement as _, IntoElement,
+    App, ClickEvent, ElementId, InteractiveElement as _, IntoElement, ParentElement as _,
-    ParentElement as _, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
+    RenderOnce, Role, SharedString, StatefulInteractiveElement as _, Styled as _, Window,
-    Styled as _, Window, px,
 };
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 
 use crate::common::{Sizable, h_flex};
 
@@ -113,11 +113,7 @@ impl RenderOnce for Link {
                     .focusable()
                     .tab_stop(true)
                     .hover(move |style| style.text_color(ramps.primary.hover))
-                    .focus_visible(|style| {
+                    .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                        style.shadow(vec![
-                            BoxShadow::new(px(0.), px(0.), colors.ring).spread_radius(px(3.)),
-                        ])
-                    })
                     .on_click(move |event, window, cx| match on_click.as_ref() {
                         Some(on_click) => on_click(event, window, cx),
                         None => {

crates/core/src/menu.rs

@@ -305,7 +305,7 @@ impl RenderOnce for Menu {
             };
 
             // Keyboard focus rides the panel across frames.
-            let focus_handle = window.use_keyed_state("menu-focus", cx, |_, cx| cx.focus_handle());
+            let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
             let scroll = window.use_keyed_state("menu-scroll", cx, |_, _| ScrollHandle::new());
 
             let selected = if *was_open.read(cx) {
@@ -334,7 +334,7 @@ impl RenderOnce for Menu {
 
             let panel = v_flex()
                 .id("menu-panel")
-                .track_focus(&focus_handle.read(cx).clone())
+                .track_focus(&focus)
                 .role(Role::Menu)
                 .aria_label(label)
                 .mt_1()
@@ -371,10 +371,9 @@ impl RenderOnce for Menu {
                         },
                         {
                             let on_change = on_change.clone();
-                            let focus = focus_handle;
                             move |_, _, window, cx| {
-                                if !focus.read(cx).contains_focused(window, cx) {
+                                if !focus.contains_focused(window, cx) {
-                                    window.focus(&focus.read(cx).clone(), cx);
+                                    window.focus(&focus, cx);
                                 }
 
                                 window.on_mouse_event({

crates/core/src/popover.rs

@@ -161,15 +161,12 @@ impl RenderOnce for Popover {
         if self.open {
             let on_change = self.on_change;
             let label = fallback_label.clone();
-
+            let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
-            let focus_handle =
-                window.use_keyed_state("popover-focus", cx, |_, cx| cx.focus_handle());
-
             let content = self.content.map(|content| content(window, cx));
 
             let panel = v_flex()
                 .id("popover-panel")
-                .track_focus(&focus_handle.read(cx).clone())
+                .track_focus(&focus)
                 .role(Role::Dialog)
                 .aria_label(label)
                 .mt_1()
@@ -201,12 +198,11 @@ impl RenderOnce for Popover {
                         },
                         {
                             let on_change = on_change.clone();
-                            let focus = focus_handle;
+                            let focus = focus;
                             move |_, _, window, cx| {
-                                if !focus.read(cx).contains_focused(window, cx) {
+                                if !focus.contains_focused(window, cx) {
-                                    window.focus(&focus.read(cx).clone(), cx);
+                                    window.focus(&focus, cx);
                                 }
-
                                 window.on_mouse_event({
                                     let on_change = on_change.clone();
                                     move |event: &MouseDownEvent, phase, window, cx| {

crates/core/src/radio.rs

@@ -1,10 +1,10 @@
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    App, BoxShadow, ElementId, InteractiveElement as _, IntoElement, ParentElement as _,
+    App, ElementId, InteractiveElement as _, IntoElement, ParentElement as _, RenderOnce, Role,
-    RenderOnce, Role, SharedString, StatefulInteractiveElement as _, Styled as _, Toggled, Window,
+    SharedString, StatefulInteractiveElement as _, Styled as _, Toggled, Window, div,
-    div, px,
 };
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 
 use crate::common::{Sizable, h_flex, v_flex};
 
@@ -178,12 +178,7 @@ where
                         row.cursor_pointer()
                             .focusable()
                             .tab_stop(true)
-                            .focus_visible(|style| {
+                            .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                                style.shadow(vec![
-                                    BoxShadow::new(px(0.), px(0.), colors.ring)
-                                        .spread_radius(px(3.)),
-                                ])
-                            })
                             .when_some(row_on_change, |row, on_change| {
                                 row.on_click(move |_, window, cx| {
                                     on_change(value.clone(), window, cx)

crates/core/src/slider.rs

@@ -3,12 +3,12 @@ use std::rc::Rc;
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    App, Bounds, BoxShadow, DispatchPhase, ElementId, InteractiveElement as _, IntoElement,
+    App, Bounds, DispatchPhase, ElementId, InteractiveElement as _, IntoElement, KeyDownEvent,
-    KeyDownEvent, MouseButton, MouseMoveEvent, MouseUpEvent, ParentElement as _, Pixels,
+    MouseButton, MouseMoveEvent, MouseUpEvent, ParentElement as _, Pixels, RenderOnce, Role,
-    RenderOnce, Role, SharedString, StatefulInteractiveElement as _, Styled as _, Window, canvas,
+    SharedString, StatefulInteractiveElement as _, Styled as _, Window, canvas, div, relative,
-    div, px, relative,
 };
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 
 use crate::common::{Sizable, h_flex};
 
@@ -138,15 +138,12 @@ impl RenderOnce for Slider {
         // The track bounds, recorded by the overlay canvas each frame,
         // turn pointer positions into values inside the listeners.
         let bounds_cell = Rc::new(Cell::new(None::<Bounds<Pixels>>));
-
         // Dragging crosses frames, so it lives in keyed element state,
         // a per-render flag would reset when the owner's update repaints.
         let dragging = window.use_keyed_state("slider-dragging", cx, |_, _| false);
-
         // A held handle gives the arrow-key listener something to check focus against,
         // and the click-to-focus behavior a target.
-        let focus = window.use_keyed_state("slider-focus", cx, |_, cx| cx.focus_handle());
+        let focus_handle = gpui_native_utils::focus_handle(&self.id, window, cx);
-        let focus_handle = focus.read(cx).clone();
 
         let set_value: ValueSetter = {
             let bounds_cell = bounds_cell.clone();
@@ -188,11 +185,7 @@ impl RenderOnce for Slider {
                 slider
                     .track_focus(&focus_handle)
                     .tab_stop(true)
-                    .focus_visible(|style| {
+                    .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                        style.shadow(vec![
-                            BoxShadow::new(px(0.), px(0.), colors.ring).spread_radius(px(3.)),
-                        ])
-                    })
                     .on_mouse_down(MouseButton::Left, move |event, window, cx| {
                         down_dragging.update(cx, |dragging, _| *dragging = true);
                         down_set_value(event.position.x, window, cx);

crates/core/src/switch.rs

@@ -2,11 +2,12 @@
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    AnimationExt as _, App, BoxShadow, ElementId, InteractiveElement as _, IntoElement,
+    AnimationExt as _, App, ElementId, InteractiveElement as _, IntoElement, ParentElement as _,
-    ParentElement as _, RenderOnce, Role, SharedString, SpringAnimation, SpringConfig,
+    RenderOnce, Role, SharedString, SpringAnimation, SpringConfig, StatefulInteractiveElement as _,
-    StatefulInteractiveElement as _, Styled as _, Toggled, Window, div, px,
+    Styled as _, Toggled, Window, div, px,
 };
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 
 use crate::common::{Sizable, h_flex};
 
@@ -122,11 +123,7 @@ impl RenderOnce for Switch {
                     .cursor_pointer()
                     .focusable()
                     .tab_stop(true)
-                    .focus_visible(|style| {
+                    .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                        style.shadow(vec![
-                            BoxShadow::new(px(0.), px(0.), colors.ring).spread_radius(px(3.)),
-                        ])
-                    })
                     .when_some(on_change, |switch, on_change| {
                         switch.on_click(move |_, window, cx| on_change(next, window, cx))
                     })

crates/core/src/toggle.rs

@@ -1,10 +1,10 @@
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    App, BoxShadow, ElementId, InteractiveElement as _, IntoElement, ParentElement as _,
+    App, ElementId, InteractiveElement as _, IntoElement, ParentElement as _, RenderOnce, Role,
-    RenderOnce, Role, SharedString, StatefulInteractiveElement as _, Styled as _, Toggled, Window,
+    SharedString, StatefulInteractiveElement as _, Styled as _, Toggled, Window,
-    px,
 };
 use gpui_native_theme::{ActiveTheme as _, Size};
+use gpui_native_utils::focus_ring;
 
 use crate::common::{Sizable, h_flex};
 
@@ -123,11 +123,7 @@ impl RenderOnce for Toggle {
                     .cursor_pointer()
                     .focusable()
                     .tab_stop(true)
-                    .focus_visible(|style| {
+                    .focus_visible(|style| style.shadow(focus_ring(colors.ring)))
-                        style.shadow(vec![
-                            BoxShadow::new(px(0.), px(0.), colors.ring).spread_radius(px(3.)),
-                        ])
-                    })
                     .when_some(on_change, |toggle, on_change| {
                         toggle.on_click(move |_, window, cx| on_change(next, window, cx))
                     })

crates/data/Cargo.toml

@@ -8,6 +8,7 @@ description = "Data-heavy GPUI components: lists, trees, tabs, sidebars — one
 gpui = { workspace = true }
 gpui-native-icons = { workspace = true }
 gpui-native-theme = { workspace = true }
+gpui-native-utils = { workspace = true }
 
 [dev-dependencies]
 gpui = { workspace = true, features = ["test-support"] }

crates/data/src/list.rs

@@ -2,12 +2,13 @@ use std::rc::Rc;
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    AnyElement, App, ElementId, FocusHandle, Hsla, InteractiveElement as _, IntoElement,
+    AnyElement, App, ElementId, FocusHandle, InteractiveElement as _, IntoElement, KeyDownEvent,
-    KeyDownEvent, ParentElement as _, Pixels, RenderOnce, Role, SharedString,
+    ParentElement as _, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
-    StatefulInteractiveElement as _, Styled as _, Window, div,
+    Styled as _, Window, div,
 };
 use gpui_native_icons::{IconRole, icon};
-use gpui_native_theme::ActiveTheme as _;
+use gpui_native_theme::{ActiveTheme as _, Theme};
+use gpui_native_utils::{nav_key, paint_selectable_row, selectable_label_color};
 
 /// The change reporter, fired with the next selection by pointer and keys.
 type ChangeHandler = Rc<dyn Fn(Option<usize>, &mut Window, &mut App)>;
@@ -116,19 +117,6 @@ impl List {
     }
 }
 
-struct ListChrome {
-    foreground: Hsla,
-    muted: Hsla,
-    muted_foreground: Hsla,
-    primary: Hsla,
-    primary_foreground: Hsla,
-    radius_sm: Pixels,
-    icon_size: Pixels,
-    text_size: Pixels,
-    /// The row count, for the rows' set-size a11y attributes.
-    count: usize,
-}
-
 impl RenderOnce for List {
     fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
         let items = match self.items {
@@ -143,40 +131,24 @@ impl RenderOnce for List {
             .map(|(index, _)| index)
             .collect();
 
-        let focus_handle = window.with_element_namespace(self.id.clone(), |window| {
+        let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
-            window.use_keyed_state("list-focus", cx, |_, cx| cx.focus_handle())
+        let theme = cx.theme();
-        });
-        let focus = focus_handle.read(cx).clone();
 
         let label = self
             .a11y_label
             .clone()
             .unwrap_or_else(|| SharedString::from(self.id.to_string()));
 
-        let chrome = {
-            let theme = cx.theme();
-            ListChrome {
-                foreground: theme.colors.foreground,
-                muted: theme.colors.muted,
-                muted_foreground: theme.colors.muted_foreground,
-                primary: theme.ramps.primary.base,
-                primary_foreground: theme.colors.primary_foreground,
-                radius_sm: theme.radius.sm,
-                icon_size: theme.sizes.medium.icon_size,
-                text_size: theme.sizes.medium.text_size,
-                count: items.len(),
-            }
-        };
-
         let rows: Vec<AnyElement> = items
             .iter()
             .enumerate()
             .map(|(index, item)| {
                 render_row(
+                    theme,
                     index,
+                    items.len(),
                     item,
                     self.selected == Some(index),
-                    &chrome,
                     &self.on_change,
                     &focus,
                 )
@@ -188,7 +160,7 @@ impl RenderOnce for List {
             .flex()
             .flex_col()
             .gap_0p5()
-            .text_size(chrome.text_size)
+            .text_size(theme.sizes.medium.text_size)
             .track_focus(&focus)
             .focusable()
             .tab_stop(true)
@@ -199,20 +171,13 @@ impl RenderOnce for List {
                 let on_change = self.on_change.clone();
 
                 move |event: &KeyDownEvent, window, cx| {
-                    let target = match event.keystroke.key.as_str() {
+                    if nav_key(&selectable, selected, &event.keystroke.key, |next| {
-                        "down" => adjacent(&selectable, selected, true),
+                        if let Some(on_change) = &on_change {
-                        "up" => adjacent(&selectable, selected, false),
+                            on_change(next, window, cx);
-                        "home" => selectable.first().copied(),
+                        }
-                        "end" => selectable.last().copied(),
+                    }) {
-                        _ => return,
+                        cx.stop_propagation();
-                    };
-                    if let Some(next) = target
-                        && Some(next) != selected
-                        && let Some(on_change) = &on_change
-                    {
-                        on_change(Some(next), window, cx);
                     }
-                    cx.stop_propagation();
                 }
             })
             .children(rows)
@@ -220,14 +185,15 @@ impl RenderOnce for List {
 }
 
 fn render_row(
+    theme: &Theme,
     index: usize,
+    count: usize,
     item: &ListItem,
     selected: bool,
-    chrome: &ListChrome,
     on_change: &Option<ChangeHandler>,
     focus: &FocusHandle,
 ) -> AnyElement {
-    let label_color = row_color(item, selected, chrome);
+    let label_color = selectable_label_color(theme, selected, item.disabled);
     let disabled = item.disabled;
 
     div()
@@ -237,20 +203,12 @@ fn render_row(
         .gap_2()
         .px_2()
         .py_1()
-        .rounded(chrome.radius_sm)
+        .rounded(theme.radius.sm)
         .role(Role::ListItem)
         .aria_selected(selected)
         .aria_position_in_set(index + 1)
-        .aria_size_of_set(chrome.count)
+        .aria_size_of_set(count)
-        .map(|row| {
+        .map(|row| paint_selectable_row(theme, row, selected, disabled))
-            if disabled {
-                row
-            } else if selected {
-                row.bg(chrome.primary)
-            } else {
-                row.hover(|row| row.bg(chrome.muted))
-            }
-        })
         .when(!disabled, |row| {
             row.cursor_pointer().on_click({
                 let on_change = on_change.clone();
@@ -264,7 +222,11 @@ fn render_row(
             })
         })
         .when_some(item.icon, |row, role| {
-            row.child(icon(role).size(chrome.icon_size).color(label_color))
+            row.child(
+                icon(role)
+                    .size(theme.sizes.medium.icon_size)
+                    .color(label_color),
+            )
         })
         .child(
             div()
@@ -278,39 +240,12 @@ fn render_row(
                     .flex_none()
                     .text_sm()
                     .text_color(if selected {
-                        chrome.primary_foreground
+                        theme.colors.primary_foreground
                     } else {
-                        chrome.muted_foreground
+                        theme.colors.muted_foreground
                     })
                     .child(detail),
             )
         })
         .into_any_element()
 }
-
-/// The row's label/icon color.
-fn row_color(item: &ListItem, selected: bool, chrome: &ListChrome) -> Hsla {
-    if item.disabled {
-        chrome.muted_foreground
-    } else if selected {
-        chrome.primary_foreground
-    } else {
-        chrome.foreground
-    }
-}
-
-/// The next selectable row in the direction.
-fn adjacent(selectable: &[usize], selected: Option<usize>, forward: bool) -> Option<usize> {
-    if forward {
-        selectable
-            .iter()
-            .copied()
-            .find(|index| Some(*index) > selected)
-    } else {
-        selectable
-            .iter()
-            .copied()
-            .rev()
-            .find(|index| Some(*index) < selected)
-    }
-}

crates/data/src/sidebar.rs

@@ -5,12 +5,13 @@ use std::rc::Rc;
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    AnyElement, App, ElementId, FocusHandle, Hsla, InteractiveElement as _, IntoElement,
+    AnyElement, App, ElementId, FocusHandle, InteractiveElement as _, IntoElement, KeyDownEvent,
-    KeyDownEvent, ParentElement as _, Pixels, RenderOnce, Role, SharedString,
+    ParentElement as _, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
-    StatefulInteractiveElement as _, Styled as _, Window, div,
+    Styled as _, Window, div,
 };
 use gpui_native_icons::{IconRole, icon};
-use gpui_native_theme::ActiveTheme as _;
+use gpui_native_theme::{ActiveTheme as _, Theme};
+use gpui_native_utils::{nav_key, paint_selectable_row, selectable_label_color};
 
 /// The change reporter, fired with the next selected row by pointer and keys.
 type ChangeHandler = Rc<dyn Fn(Option<usize>, &mut Window, &mut App)>;
@@ -148,36 +149,8 @@ impl Sidebar {
     }
 }
 
-struct SidebarChrome {
-    foreground: Hsla,
-    muted: Hsla,
-    muted_foreground: Hsla,
-    primary: Hsla,
-    primary_foreground: Hsla,
-    radius_sm: Pixels,
-    icon_size: Pixels,
-    text_size: Pixels,
-    /// The entry count, for the rows' set-size a11y attributes.
-    count: usize,
-}
-
 impl RenderOnce for Sidebar {
     fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
-        let chrome = {
-            let theme = cx.theme();
-            SidebarChrome {
-                foreground: theme.colors.foreground,
-                muted: theme.colors.muted,
-                muted_foreground: theme.colors.muted_foreground,
-                primary: theme.ramps.primary.base,
-                primary_foreground: theme.colors.primary_foreground,
-                radius_sm: theme.radius.sm,
-                icon_size: theme.sizes.medium.icon_size,
-                text_size: theme.sizes.medium.text_size,
-                count: 0,
-            }
-        };
-
         let entries = match self.entries {
             Some(build) => build(window, cx),
             None => Vec::new(),
@@ -195,30 +168,26 @@ impl RenderOnce for Sidebar {
             .collect();
 
         // Keyboard focus rides the container across frames.
-        let focus_handle = window.with_element_namespace(self.id.clone(), |window| {
+        let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
-            window.use_keyed_state("sidebar-focus", cx, |_, cx| cx.focus_handle())
-        });
-        let focus = focus_handle.read(cx).clone();
 
         let label = self
             .a11y_label
             .clone()
             .unwrap_or_else(|| SharedString::from(self.id.to_string()));
 
-        let chrome = SidebarChrome {
+        // Entry paint reads the theme through this borrow.
-            count: entries.len(),
+        let theme = cx.theme();
-            ..chrome
-        };
 
         let children: Vec<AnyElement> = entries
             .iter()
             .enumerate()
             .map(|(index, entry)| {
                 render_entry(
+                    theme,
                     entry,
                     index,
+                    entries.len(),
                     self.selected == Some(index),
-                    &chrome,
                     &self.on_change,
                     &focus,
                 )
@@ -230,7 +199,7 @@ impl RenderOnce for Sidebar {
             .flex()
             .flex_col()
             .gap_0p5()
-            .text_size(chrome.text_size)
+            .text_size(theme.sizes.medium.text_size)
             .track_focus(&focus)
             .focusable()
             .tab_stop(true)
@@ -240,20 +209,13 @@ impl RenderOnce for Sidebar {
                 let selected = self.selected;
                 let on_change = self.on_change.clone();
                 move |event: &KeyDownEvent, window, cx| {
-                    let target = match event.keystroke.key.as_str() {
+                    if nav_key(&selectable, selected, &event.keystroke.key, |next| {
-                        "down" => adjacent(&selectable, selected, true),
+                        if let Some(on_change) = &on_change {
-                        "up" => adjacent(&selectable, selected, false),
+                            on_change(next, window, cx);
-                        "home" => selectable.first().copied(),
+                        }
-                        "end" => selectable.last().copied(),
+                    }) {
-                        _ => return,
+                        cx.stop_propagation();
-                    };
-                    if let Some(next) = target
-                        && Some(next) != selected
-                        && let Some(on_change) = &on_change
-                    {
-                        on_change(Some(next), window, cx);
                     }
-                    cx.stop_propagation();
                 }
             })
             .children(children)
@@ -261,10 +223,11 @@ impl RenderOnce for Sidebar {
 }
 
 fn render_entry(
+    theme: &Theme,
     entry: &SidebarEntry,
     index: usize,
+    count: usize,
     selected: bool,
-    chrome: &SidebarChrome,
     on_change: &Option<ChangeHandler>,
     focus: &FocusHandle,
 ) -> AnyElement {
@@ -275,7 +238,7 @@ fn render_entry(
             .pb_1()
             .text_sm()
             .font_weight(gpui::FontWeight::MEDIUM)
-            .text_color(chrome.muted_foreground)
+            .text_color(theme.colors.muted_foreground)
             .child(label.clone())
             .into_any_element(),
         SidebarEntry::Row {
@@ -284,13 +247,7 @@ fn render_entry(
             detail,
             disabled: row_disabled,
         } => {
-            let label_color = if *row_disabled {
+            let label_color = selectable_label_color(theme, selected, *row_disabled);
-                chrome.muted_foreground
-            } else if selected {
-                chrome.primary_foreground
-            } else {
-                chrome.foreground
-            };
 
             let mut row = div()
                 .id(("sidebar-row", index))
@@ -299,20 +256,12 @@ fn render_entry(
                 .gap_2()
                 .px_2()
                 .py_1()
-                .rounded(chrome.radius_sm)
+                .rounded(theme.radius.sm)
                 .role(Role::ListItem)
                 .aria_selected(selected)
                 .aria_position_in_set(index + 1)
-                .aria_size_of_set(chrome.count)
+                .aria_size_of_set(count)
-                .map(|row| {
+                .map(|row| paint_selectable_row(theme, row, selected, *row_disabled));
-                    if *row_disabled {
-                        row
-                    } else if selected {
-                        row.bg(chrome.primary)
-                    } else {
-                        row.hover(|row| row.bg(chrome.muted))
-                    }
-                });
 
             if !*row_disabled {
                 row = row.cursor_pointer().on_click({
@@ -328,7 +277,11 @@ fn render_entry(
             }
 
             row = row.when_some(*row_icon, |row, role| {
-                row.child(icon(role).size(chrome.icon_size).color(label_color))
+                row.child(
+                    icon(role)
+                        .size(theme.sizes.medium.icon_size)
+                        .color(label_color),
+                )
             });
 
             row = row.child(div().flex_1().text_color(label_color).child(label.clone()));
@@ -339,9 +292,9 @@ fn render_entry(
                         .flex_none()
                         .text_sm()
                         .text_color(if selected {
-                            chrome.primary_foreground
+                            theme.colors.primary_foreground
                         } else {
-                            chrome.muted_foreground
+                            theme.colors.muted_foreground
                         })
                         .child(detail.clone()),
                 );
@@ -351,19 +304,3 @@ fn render_entry(
         }
     }
 }
-
-/// The next selectable row in the direction.
-fn adjacent(selectable: &[usize], selected: Option<usize>, forward: bool) -> Option<usize> {
-    if forward {
-        selectable
-            .iter()
-            .copied()
-            .find(|index| Some(*index) > selected)
-    } else {
-        selectable
-            .iter()
-            .copied()
-            .rev()
-            .find(|index| Some(*index) < selected)
-    }
-}

crates/data/src/tabs.rs

@@ -2,12 +2,13 @@ use std::rc::Rc;
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    AnyElement, App, ElementId, Hsla, InteractiveElement as _, IntoElement, KeyDownEvent,
+    AnyElement, App, ElementId, InteractiveElement as _, IntoElement, KeyDownEvent,
-    ParentElement as _, Pixels, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
+    ParentElement as _, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
     Styled as _, Window, div,
 };
 use gpui_native_icons::{IconRole, icon};
-use gpui_native_theme::ActiveTheme as _;
+use gpui_native_theme::{ActiveTheme as _, Theme};
+use gpui_native_utils::adjacent_selectable;
 
 /// The change reporter, fired with the next selected tab by pointer and keys.
 type ChangeHandler = Rc<dyn Fn(usize, &mut Window, &mut App)>;
@@ -105,36 +106,8 @@ impl Tabs {
     }
 }
 
-struct TabsChrome {
-    foreground: Hsla,
-    muted: Hsla,
-    muted_foreground: Hsla,
-    primary: Hsla,
-    border: Hsla,
-    radius_sm: Pixels,
-    icon_size: Pixels,
-    text_size: Pixels,
-    /// The strip's selected index; re-selecting it reports nothing.
-    selected: usize,
-}
-
 impl RenderOnce for Tabs {
     fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
-        let chrome = {
-            let theme = cx.theme();
-            TabsChrome {
-                foreground: theme.colors.foreground,
-                muted: theme.colors.muted,
-                muted_foreground: theme.colors.muted_foreground,
-                primary: theme.ramps.primary.base,
-                border: theme.colors.border,
-                radius_sm: theme.radius.sm,
-                icon_size: theme.sizes.medium.icon_size,
-                text_size: theme.sizes.medium.text_size,
-                selected: self.selected,
-            }
-        };
-
         let tabs = match self.tabs {
             Some(build) => build(window, cx),
             None => Vec::new(),
@@ -147,11 +120,8 @@ impl RenderOnce for Tabs {
             .map(|(index, _)| index)
             .collect();
 
-        // Keyboard focus rides the strip across frames.
+        let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
-        let focus_handle = window.with_element_namespace(self.id.clone(), |window| {
+        let theme = cx.theme();
-            window.use_keyed_state("tabs-focus", cx, |_, cx| cx.focus_handle())
-        });
-        let focus = focus_handle.read(cx).clone();
 
         let label = self
             .a11y_label
@@ -163,10 +133,11 @@ impl RenderOnce for Tabs {
             .enumerate()
             .map(|(index, tab)| {
                 render_tab(
+                    theme,
                     tab,
                     index,
                     self.selected == index,
-                    &chrome,
+                    self.selected,
                     &self.on_change,
                     &focus,
                 )
@@ -178,8 +149,8 @@ impl RenderOnce for Tabs {
             .flex()
             .gap_1()
             .border_b_1()
-            .border_color(chrome.border)
+            .border_color(theme.colors.border)
-            .text_size(chrome.text_size)
+            .text_size(theme.sizes.medium.text_size)
             .track_focus(&focus)
             .focusable()
             .tab_stop(true)
@@ -190,8 +161,8 @@ impl RenderOnce for Tabs {
                 let on_change = self.on_change.clone();
                 move |event: &KeyDownEvent, window, cx| {
                     let target = match event.keystroke.key.as_str() {
-                        "right" => adjacent(&selectable, selected, true),
+                        "right" => adjacent_selectable(&selectable, Some(selected), true),
-                        "left" => adjacent(&selectable, selected, false),
+                        "left" => adjacent_selectable(&selectable, Some(selected), false),
                         "home" => selectable.first().copied(),
                         "end" => selectable.last().copied(),
                         _ => return,
@@ -210,19 +181,20 @@ impl RenderOnce for Tabs {
 }
 
 fn render_tab(
+    theme: &Theme,
     tab: &Tab,
     index: usize,
     selected: bool,
-    chrome: &TabsChrome,
+    selected_index: usize,
     on_change: &Option<ChangeHandler>,
     focus: &gpui::FocusHandle,
 ) -> AnyElement {
     let label_color = if tab.disabled {
-        chrome.muted_foreground
+        theme.colors.muted_foreground
     } else if selected {
-        chrome.primary
+        theme.ramps.primary.base
     } else {
-        chrome.foreground
+        theme.colors.foreground
     };
 
     let mut strip_tab = div()
@@ -232,31 +204,34 @@ fn render_tab(
         .gap_1p5()
         .px_2()
         .py_1()
-        .rounded_tl(chrome.radius_sm)
+        .rounded_tl(theme.radius.sm)
-        .rounded_tr(chrome.radius_sm)
+        .rounded_tr(theme.radius.sm)
         .role(Role::Tab)
         .aria_selected(selected)
         .text_color(label_color)
         .when(selected, |strip_tab| {
-            // The underline sits on the strip's hairline, marking the active
+            strip_tab
-            // tab the way a native tab bar does.
+                .border_b_2()
-            strip_tab.border_b_2().border_color(chrome.primary)
+                .border_color(theme.ramps.primary.base)
         })
         .when(!tab.disabled && !selected, |strip_tab| {
-            strip_tab.hover(|strip_tab| strip_tab.bg(chrome.muted))
+            strip_tab.hover(|strip_tab| strip_tab.bg(theme.colors.muted))
         })
         .child(
             div()
                 .flex_none()
                 .pb_0p5()
                 .when_some(tab.icon, |strip_tab, role| {
-                    strip_tab.child(icon(role).size(chrome.icon_size * 0.75).color(label_color))
+                    strip_tab.child(
+                        icon(role)
+                            .size(theme.sizes.medium.icon_size * 0.75)
+                            .color(label_color),
+                    )
                 }),
         )
-        .child(strip_tab_label(tab.label.clone(), selected, chrome));
+        .child(strip_tab_label(tab.label.clone(), selected, theme));
 
     if !tab.disabled {
-        let selected_index = chrome.selected;
         strip_tab = strip_tab.cursor_pointer().on_click({
             let on_change = on_change.clone();
             let focus = focus.clone();
@@ -274,26 +249,13 @@ fn render_tab(
     strip_tab.into_any_element()
 }
 
-fn strip_tab_label(label: SharedString, selected: bool, chrome: &TabsChrome) -> AnyElement {
+fn strip_tab_label(label: SharedString, selected: bool, theme: &Theme) -> AnyElement {
     div()
         .text_color(if selected {
-            chrome.primary
+            theme.ramps.primary.base
         } else {
-            chrome.foreground
+            theme.colors.foreground
         })
         .child(label)
         .into_any_element()
 }
-
-/// The next selectable tab in the direction.
-fn adjacent(selectable: &[usize], selected: usize, forward: bool) -> Option<usize> {
-    if forward {
-        selectable.iter().copied().find(|index| *index > selected)
-    } else {
-        selectable
-            .iter()
-            .copied()
-            .rev()
-            .find(|index| *index < selected)
-    }
-}

crates/data/src/tree.rs

@@ -2,12 +2,13 @@ use std::rc::Rc;
 
 use gpui::prelude::FluentBuilder as _;
 use gpui::{
-    AnyElement, App, ElementId, FocusHandle, Hsla, InteractiveElement as _, IntoElement,
+    AnyElement, App, ElementId, FocusHandle, InteractiveElement as _, IntoElement, KeyDownEvent,
-    KeyDownEvent, ParentElement as _, Pixels, RenderOnce, Role, SharedString,
+    ParentElement as _, RenderOnce, Role, SharedString, StatefulInteractiveElement as _,
-    StatefulInteractiveElement as _, Styled as _, Window, div,
+    Styled as _, Window, div,
 };
 use gpui_native_icons::{IconRole, icon};
-use gpui_native_theme::ActiveTheme as _;
+use gpui_native_theme::{ActiveTheme as _, Theme};
+use gpui_native_utils::{nav_key, paint_selectable_row, selectable_label_color};
 
 /// The change reporter, fired with the next selection by pointer and keys.
 type ChangeHandler = Rc<dyn Fn(Option<usize>, &mut Window, &mut App)>;
@@ -143,38 +144,8 @@ impl Tree {
     }
 }
 
-struct TreeChrome {
-    foreground: Hsla,
-    muted: Hsla,
-    muted_foreground: Hsla,
-    primary: Hsla,
-    primary_foreground: Hsla,
-    radius_sm: Pixels,
-    icon_size: Pixels,
-    padding_x: Pixels,
-    text_size: Pixels,
-    /// The row count, for the rows' set-size a11y attributes.
-    count: usize,
-}
-
 impl RenderOnce for Tree {
     fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
-        let chrome = {
-            let theme = cx.theme();
-            TreeChrome {
-                foreground: theme.colors.foreground,
-                muted: theme.colors.muted,
-                muted_foreground: theme.colors.muted_foreground,
-                primary: theme.ramps.primary.base,
-                primary_foreground: theme.colors.primary_foreground,
-                radius_sm: theme.radius.sm,
-                icon_size: theme.sizes.medium.icon_size,
-                padding_x: theme.sizes.medium.padding_x,
-                text_size: theme.sizes.medium.text_size,
-                count: 0,
-            }
-        };
-
         let items = match self.items {
             Some(build) => build(window, cx),
             None => Vec::new(),
@@ -188,30 +159,24 @@ impl RenderOnce for Tree {
             .collect();
 
         // Keyboard focus rides the container across frames.
-        let focus_handle = window.with_element_namespace(self.id.clone(), |window| {
+        let focus = gpui_native_utils::focus_handle(&self.id, window, cx);
-            window.use_keyed_state("tree-focus", cx, |_, cx| cx.focus_handle())
-        });
-        let focus = focus_handle.read(cx).clone();
 
         let label = self
             .a11y_label
             .clone()
             .unwrap_or_else(|| SharedString::from(self.id.to_string()));
 
-        let chrome = TreeChrome {
+        let theme = cx.theme();
-            count: items.len(),
-            ..chrome
-        };
 
         let rows: Vec<AnyElement> = items
             .iter()
             .enumerate()
-            .map(|(index, item)| {
+            .map(|(index, _item)| {
                 render_row(
-                    item,
+                    theme,
+                    &items,
                     index,
                     self.selected == Some(index),
-                    &chrome,
                     &self.on_change,
                     &self.on_disclosure,
                     &focus,
@@ -224,7 +189,7 @@ impl RenderOnce for Tree {
             .flex()
             .flex_col()
             .gap_0p5()
-            .text_size(chrome.text_size)
+            .text_size(theme.sizes.medium.text_size)
             .track_focus(&focus)
             .focusable()
             .tab_stop(true)
@@ -235,39 +200,15 @@ impl RenderOnce for Tree {
                 let on_change = self.on_change.clone();
                 let on_disclosure = self.on_disclosure.clone();
                 move |event: &KeyDownEvent, window, cx| {
+                    if nav_key(&selectable, selected, &event.keystroke.key, |next| {
+                        if let Some(on_change) = &on_change {
+                            on_change(next, window, cx);
+                        }
+                    }) {
+                        cx.stop_propagation();
+                        return;
+                    }
                     match event.keystroke.key.as_str() {
-                        "down" => {
-                            if let Some(next) = adjacent(&selectable, selected, true)
-                                && Some(next) != selected
-                                && let Some(on_change) = &on_change
-                            {
-                                on_change(Some(next), window, cx);
-                            }
-                        }
-                        "up" => {
-                            if let Some(next) = adjacent(&selectable, selected, false)
-                                && Some(next) != selected
-                                && let Some(on_change) = &on_change
-                            {
-                                on_change(Some(next), window, cx);
-                            }
-                        }
-                        "home" => {
-                            if let Some(first) = selectable.first()
-                                && selected != Some(*first)
-                                && let Some(on_change) = &on_change
-                            {
-                                on_change(Some(*first), window, cx);
-                            }
-                        }
-                        "end" => {
-                            if let Some(last) = selectable.last()
-                                && selected != Some(*last)
-                                && let Some(on_change) = &on_change
-                            {
-                                on_change(Some(*last), window, cx);
-                            }
-                        }
                         "left" | "right" => {
                             let expanding = event.keystroke.key == "right";
                             if let Some(index) = selected
@@ -290,19 +231,21 @@ impl RenderOnce for Tree {
 }
 
 fn render_row(
-    item: &TreeItem,
+    theme: &Theme,
+    items: &[TreeItem],
     index: usize,
     selected: bool,
-    chrome: &TreeChrome,
     on_change: &Option<ChangeHandler>,
     on_disclosure: &Option<DisclosureHandler>,
     focus: &FocusHandle,
 ) -> AnyElement {
-    let label_color = row_color(item, selected, chrome);
+    let item = &items[index];
+    let count = items.len();
+    let label_color = selectable_label_color(theme, selected, item.disabled);
     let disabled = item.disabled;
 
     // One indent step per depth level, on the theme's horizontal padding.
-    let indent = chrome.padding_x * (item.depth as f32 + 1.0);
+    let indent = theme.sizes.medium.padding_x * (item.depth as f32 + 1.0);
 
     div()
         .id(("tree-item", index))
@@ -312,21 +255,13 @@ fn render_row(
         .pl(indent)
         .pr_2()
         .py_1()
-        .rounded(chrome.radius_sm)
+        .rounded(theme.radius.sm)
         .role(Role::TreeItem)
         .aria_selected(selected)
         .aria_level(item.depth + 1)
-        .aria_size_of_set(chrome.count)
+        .aria_size_of_set(count)
         .when(item.expandable, |row| row.aria_expanded(item.expanded))
-        .map(|row| {
+        .map(|row| paint_selectable_row(theme, row, selected, disabled))
-            if disabled {
-                row
-            } else if selected {
-                row.bg(chrome.primary)
-            } else {
-                row.hover(|row| row.bg(chrome.muted))
-            }
-        })
         .when(!disabled, |row| {
             row.cursor_pointer().on_click({
                 let on_change = on_change.clone();
@@ -344,11 +279,15 @@ fn render_row(
             index,
             disabled,
             selected,
-            chrome,
+            theme,
             on_disclosure,
         ))
         .when_some(item.icon, |row, role| {
-            row.child(icon(role).size(chrome.icon_size).color(label_color))
+            row.child(
+                icon(role)
+                    .size(theme.sizes.medium.icon_size)
+                    .color(label_color),
+            )
         })
         .child(
             div()
@@ -365,20 +304,20 @@ fn render_disclosure(
     index: usize,
     disabled: bool,
     selected: bool,
-    chrome: &TreeChrome,
+    theme: &Theme,
     on_disclosure: &Option<DisclosureHandler>,
 ) -> AnyElement {
     let glyph_color = if disabled {
-        chrome.muted_foreground
+        theme.colors.muted_foreground
     } else if selected {
-        chrome.primary_foreground
+        theme.colors.primary_foreground
     } else {
-        chrome.muted_foreground
+        theme.colors.muted_foreground
     };
 
     let cell = div()
         .flex_none()
-        .size(chrome.icon_size)
+        .size(theme.sizes.medium.icon_size)
         .flex()
         .items_center()
         .justify_center()
@@ -388,7 +327,7 @@ fn render_disclosure(
             } else {
                 IconRole::ChevronRight
             })
-            .size(chrome.icon_size * 0.75)
+            .size(theme.sizes.medium.icon_size * 0.75)
             .color(glyph_color),
         );
 
@@ -410,30 +349,3 @@ fn render_disclosure(
         cell.into_any_element()
     }
 }
-
-/// The row's label/icon color.
-fn row_color(item: &TreeItem, selected: bool, chrome: &TreeChrome) -> Hsla {
-    if item.disabled {
-        chrome.muted_foreground
-    } else if selected {
-        chrome.primary_foreground
-    } else {
-        chrome.foreground
-    }
-}
-
-/// The next selectable row in the direction.
-fn adjacent(selectable: &[usize], selected: Option<usize>, forward: bool) -> Option<usize> {
-    if forward {
-        selectable
-            .iter()
-            .copied()
-            .find(|index| Some(*index) > selected)
-    } else {
-        selectable
-            .iter()
-            .copied()
-            .rev()
-            .find(|index| Some(*index) < selected)
-    }
-}

crates/utils/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "gpui-native-utils"
+version = "0.1.0"
+edition = "2024"
+description = "Small helpers shared by the component crates: layout shorthands, focus plumbing, list navigation, selectable-row paint"
+
+[dependencies]
+gpui = { workspace = true }
+gpui-native-theme = { workspace = true }

crates/utils/src/lib.rs

@@ -0,0 +1,98 @@
+use gpui::prelude::FluentBuilder as _;
+use gpui::{
+    App, BoxShadow, Div, ElementId, FocusHandle, Hsla, IntoElement, StatefulInteractiveElement,
+    Styled, Window, div, px,
+};
+use gpui_native_theme::Theme;
+
+/// A row whose children center on the cross axis.
+pub fn h_flex() -> Div {
+    div().flex().flex_row().items_center()
+}
+
+/// A column whose children stack on the main axis.
+pub fn v_flex() -> Div {
+    div().flex().flex_col()
+}
+
+/// Returns a focus handle for the given element ID.
+pub fn focus_handle(id: &ElementId, window: &mut Window, cx: &mut App) -> FocusHandle {
+    window
+        .with_element_namespace(id.clone(), |window| {
+            window.use_keyed_state("focus-handle", cx, |_, cx| cx.focus_handle())
+        })
+        .read(cx)
+        .clone()
+}
+
+/// Returns a focus ring shadow with the given color.
+pub fn focus_ring(color: Hsla) -> Vec<BoxShadow> {
+    vec![BoxShadow::new(px(0.), px(0.), color).spread_radius(px(3.))]
+}
+
+/// The next selectable row in the direction, or `None` at the ends.
+pub fn adjacent_selectable(
+    selectable: &[usize],
+    selected: Option<usize>,
+    forward: bool,
+) -> Option<usize> {
+    if forward {
+        selectable
+            .iter()
+            .copied()
+            .find(|index| Some(*index) > selected)
+    } else {
+        selectable
+            .iter()
+            .copied()
+            .rev()
+            .find(|index| Some(*index) < selected)
+    }
+}
+
+/// Whether the given key is a vertical navigation key.
+pub fn nav_key<S>(selectable: &[usize], selected: Option<usize>, key: &str, select: S) -> bool
+where
+    S: FnOnce(Option<usize>),
+{
+    let target = match key {
+        "down" => adjacent_selectable(selectable, selected, true),
+        "up" => adjacent_selectable(selectable, selected, false),
+        "home" => selectable.first().copied(),
+        "end" => selectable.last().copied(),
+        _ => return false,
+    };
+    if let Some(next) = target
+        && Some(next) != selected
+    {
+        select(Some(next));
+    }
+    true
+}
+
+/// A selectable row's label and icon color.
+pub fn selectable_label_color(theme: &Theme, selected: bool, disabled: bool) -> Hsla {
+    if disabled {
+        theme.colors.muted_foreground
+    } else if selected {
+        theme.colors.primary_foreground
+    } else {
+        theme.colors.foreground
+    }
+}
+
+/// A selectable row's background.
+pub fn paint_selectable_row<R>(theme: &Theme, row: R, selected: bool, disabled: bool) -> R
+where
+    R: IntoElement + Styled + StatefulInteractiveElement,
+{
+    row.map(|row| {
+        if disabled {
+            row
+        } else if selected {
+            row.bg(theme.ramps.primary.base)
+        } else {
+            row.hover(|row| row.bg(theme.colors.muted))
+        }
+    })
+}

docs/PLAN.md

@@ -47,6 +47,7 @@ gpui-native-kit/                 # repo root = workspace root
 ├── crates/
 │   ├── theme/                   # gpui-native-theme: the native theme engine
 │   ├── icons/                   # gpui-native-icons: system icons + bundled fallback
+│   ├── utils/                   # gpui-native-utils: internal shared helpers (not re-exported by the facade)
 │   ├── core/                    # gpui-native-core: components every app needs
 │   │                            # (one cargo feature per component)
 │   ├── data/                    # gpui-native-data: List, Tree, Tabs, Sidebar (one cargo feature each)
@@ -321,7 +322,7 @@ Dropped from rev 3: D2, D5, D9 (port-era decisions); the review gate returns in
 4. ~~Phase D input~~ ✅ — single-line Input (unit 10) + the §6.2 completion pass (modifiers, undo/redo, read-only, actions + key context, caret blink, paint polish). NumberInput and multiline remain open as deferred units.
 5. ~~Phase E overlays~~ ✅ — Popover (unit 11), ScrollArea (unit 11.5), Menu (unit 12), Tooltip + Dialog/AlertDialog + Toast (unit 11+ row; Sheet dropped). Phase gate held: escape/dismiss semantics and focus behavior per overlay.
 6. ~~Unit 14 — motion, per component (§6 row 14, D21)~~ ✅ Landed in five passes (2026-10-30): (a) theme `reduce_motion` → `cx.set_reduce_motion` in `reapply`; (b) Switch thumb `with_spring`; (c) Toast 8 px slide-in; (d) Dialog scrim enters with the panel; (e) Progress 30 fps cap. Exits and hover washes stay deferred (§6 deferred list).
-7. ~~Phase F, data first~~ ✅ data complete (2026-10-30) — `crates/data` opened with List, then Tree, Tabs, Sidebar (the dead `sheet` feature dropped from core along the way; Table dropped from the roadmap). Remaining Phase F: **Windows/GNOME/KDE/Omarchy theme sources** and the **Segoe Fluent/freedesktop icon resolvers**, slotted in as verification environments allow — a source may state `Motion.overlay` when it needs platform timing (§5.5) — with side-by-side gallery screenshots per platform. NumberInput/multiline return as deferred units when needed.
+7. ~~Phase F, data first~~ ✅ data complete (2026-10-30) — `crates/data` opened with List, then Tree, Tabs, Sidebar (the dead `sheet` feature dropped from core along the way; Table dropped from the roadmap). Also extracted `crates/utils` (2026-10-30): `h_flex`/`v_flex` (core's `common` re-exports them), `focus_handle` (the namespaced keyed handle, 8 call sites), `focus_ring` (7 sites), `adjacent_selectable` + `nav_key` (4 sites), and the selectable-row paint helpers `selectable_label_color`/`paint_selectable_row` (3 sites, reading `&Theme` directly — no intermediate color struct) — `core` and `data` depend on it; the facade doesn't re-export it. Remaining Phase F: **Windows/GNOME/KDE/Omarchy theme sources** and the **Segoe Fluent/freedesktop icon resolvers**, slotted in as verification environments allow — a source may state `Motion.overlay` when it needs platform timing (§5.5) — with side-by-side gallery screenshots per platform. NumberInput/multiline return as deferred units when needed.
 8. Then — Phase G: pickers, polish, → 0.1; start `crates/editor` if wanted.
 
 Batched polish candidates between units: scrollbar auto-hide + horizontal thumb, `Undo`/`Redo` menu events.