button: expose preferred tooltip placement (#2971)

Button tooltips always use automatic positioning, even though the
existing tooltip overlay supports a preferred side. This adds
`tooltip_placement(Placement)` so callers can choose that side without
replacing the button’s tooltip handling.

```rust
Button::new("search")
    .label("Search")
    .tooltip("Find a document")
    .tooltip_placement(Placement::Left)
```

It works with both `tooltip(...)` and `tooltip_with_action(...)`. The
side is a preference, not a fixed position. The existing positioner
still flips and clamps the tooltip when space is limited. Omitting the
setting preserves automatic positioning. Setting it without tooltip
content does nothing.

## Screenshots

| Left | Right |
| --- | --- |
| ![Search tooltip on the
left](https://github.com/user-attachments/assets/9ead6676-b4fd-4084-83cf-17231a563c3a)
| ![Tooltip on the right of Hover
me](https://github.com/user-attachments/assets/a44cbf23-f504-43ff-b100-1d369017b988)
|
| **Bottom, with shortcut** | **Top requested, falls back below** |
| ![Info tooltip below the button with its
shortcut](https://github.com/user-attachments/assets/993918b3-d9f9-4e2e-8d42-d29ac06b4d94)
| ![At the top edge, the tooltip falls back below the
button](https://github.com/user-attachments/assets/1f5ab695-cb31-43b8-8c56-0266563c5596)
|

## Video

Recorded during my manual testing:


https://github.com/user-attachments/assets/094f000b-847b-4504-a31d-3fed9ecdd35d

## How to Test

On macOS:

```sh
MTL_HUD_ENABLED=1 ./script/run-story-macos Tooltip
```

Hover **Search**, **Info**, and **Hover me**, moving away between
buttons. Their tooltips should appear on the left, below with the
shortcut, and on the right.

To check fallback near the window edge:

```sh
cargo run -p tooltip_top_edge --locked
```

Hover the top button. It requests `Top`, but the tooltip should appear
below because there is no room above.

<details>
<summary>Automated checks</summary>

```sh
cargo test -p gpui-base -p gpui-component --lib --locked
cargo clippy -p gpui-base -p gpui-component -p gpui-component-story --all-targets --locked -- -D warnings
```

771 base tests and 418 component tests passed. Strict Clippy and
formatting passed. The top-edge example also passed its build and strict
Clippy check. There is no new automated test for the Button forwarding
method. Placement was checked visually on macOS.

</details>

## Checklist

- [x] Read
[CONTRIBUTING.md](https://github.com/longbridge/gpui-kit/blob/main/CONTRIBUTING.md)
and followed the guidelines.
- [x] Reviewed the changes, including the AI-assisted code.
- [x] Ran and manually tested the related Story examples on macOS.

This change is not platform-specific. Windows and Linux runtime and
performance were not tested.

## AI assistance

I tested the change in my application, then asked OpenAI’s `gpt-6-astra`
to extract it into this PR. The agent prepared the patch, examples,
verification scripts, and description, and ran the automated checks. I
reviewed the extracted patch, requested corrections, and tested it
myself on macOS.

Author: grishy

crates/component/src/button/button.rs

@@ -2,8 +2,8 @@ use std::rc::Rc;
 
 use crate::ThemeStyled as _;
 use crate::{
-    ActiveTheme, Colorize as _, Disableable, Icon, RoleOverride, Selectable, Sizable, Size,
-    StyleSized, StyledExt,
+    ActiveTheme, Colorize as _, Disableable, Icon, Placement, RoleOverride, Selectable, Sizable,
+    Size, StyleSized, StyledExt,
     button::ButtonIcon,
     h_flex,
     select::Caret,
@@ -209,6 +209,7 @@ pub struct Button {
         SharedString,
         Option<(Rc<Box<dyn gpui::Action>>, Option<SharedString>)>,
     )>,
+    tooltip_placement: Option<Placement>,
     tooltip_builder: Option<Rc<dyn Fn(&mut Window, &mut App) -> gpui::AnyView>>,
     on_click: Option<Rc<dyn Fn(&ClickEvent, &mut Window, &mut App)>>,
     on_hover: Option<Rc<dyn Fn(&bool, &mut Window, &mut App)>>,
@@ -252,6 +253,7 @@ impl Button {
             border_edges: Edges::all(true),
             size: Size::Medium,
             tooltip: None,
+            tooltip_placement: None,
             tooltip_builder: None,
             on_click: None,
             focus_ring_enabled: true,
@@ -368,6 +370,15 @@ impl Button {
         self
     }
 
+    /// Prefer a side for the tooltip, falling back when it does not fit.
+    ///
+    /// Applies to [`Self::tooltip`] and [`Self::tooltip_with_action`].
+    /// Omitting placement keeps automatic positioning.
+    pub fn tooltip_placement(mut self, placement: Placement) -> Self {
+        self.tooltip_placement = Some(placement);
+        self
+    }
+
     /// Set the tooltip of the button with action to show keybinding.
     pub fn tooltip_with_action(
         mut self,
@@ -536,6 +547,7 @@ impl RenderOnce for Button {
         let hoverable = self.hoverable();
         let disabled = self.disabled;
         let loading = self.loading;
+        let tooltip_placement = self.tooltip_placement;
         let hover_group = self.hover_group;
         let hover_group_held = self.hover_group_held;
         let mut base = self.base;
@@ -780,9 +792,11 @@ impl RenderOnce for Button {
         })
         .map(|this| {
             if let Some(builder) = self.tooltip_builder {
-                this.managed_tooltip(move |window, cx| builder(window, cx))
+                this.managed_tooltip_with_placement(tooltip_placement, move |window, cx| {
+                    builder(window, cx)
+                })
             } else if let Some((tooltip, action)) = self.tooltip {
-                this.managed_tooltip(move |window, cx| {
+                this.managed_tooltip_with_placement(tooltip_placement, move |window, cx| {
                     Tooltip::new(tooltip.clone())
                         .when_some(action.clone(), |this, (action, context)| {
                             this.action(

crates/story/src/stories/tooltip_story.rs

@@ -2,7 +2,7 @@ use gpui_kit::prelude::FluentBuilder as _;
 use gpui_kit::*;
 
 use gpui_kit::component::{
-    IconName,
+    IconName, Placement,
     button::{Button, ButtonVariant, ButtonVariants, Toggle},
     checkbox::Checkbox,
     clipboard::Clipboard,
@@ -46,7 +46,7 @@ impl Story for TooltipStory {
     }
 
     fn description() -> &'static str {
-        "Describe a control on hover or keyboard focus."
+        "Describe a control on hover."
     }
 
     fn new_view(window: &mut Window, cx: &mut App) -> Entity<impl Render> {
@@ -75,22 +75,29 @@ impl Render for TooltipStory {
             .gap_3()
             .child(
                 section("Button")
-                    .description("Add plain text or a keyboard shortcut hint.")
+                    .description("Prefer the left, bottom, or right side, with an optional keyboard shortcut hint.")
                     .child(
                         Button::new("btn0")
                             .label("Search")
                             .with_variant(ButtonVariant::Primary)
-                            .tooltip("This is a search Button."),
+                            .tooltip("This is a search Button.")
+                            .tooltip_placement(Placement::Left),
                     )
-                    .child(Button::new("btn1").label("Info").tooltip_with_action(
-                        "This is a tooltip with Action for display keybinding.",
-                        &Info,
-                        Some("Tooltip"),
-                    ))
                     .child(
-                        Button::new("btn3")
+                        Button::new("btn1")
+                            .label("Info")
+                            .tooltip_with_action(
+                                "This is a tooltip with Action for display keybinding.",
+                                &Info,
+                                Some("Tooltip"),
+                            )
+                            .tooltip_placement(Placement::Bottom),
+                    )
+                    .child(
+                        Button::new("btn2")
                             .label("Hover me")
-                            .tooltip("This is tooltip 3"),
+                            .tooltip("This tooltip prefers the right side.")
+                            .tooltip_placement(Placement::Right),
                     ),
             )
             .child(

examples/tooltip_top_edge/src/main.rs

@@ -1,4 +1,4 @@
-use gpui_kit::component::{ActiveTheme as _, Root, button::*};
+use gpui_kit::component::{ActiveTheme as _, Placement, Root, button::*};
 use gpui_kit::*;
 
 struct TooltipTopEdgeExample;
@@ -15,7 +15,8 @@ impl Render for TooltipTopEdgeExample {
                     Button::new("top-edge-tooltip")
                         .primary()
                         .label("Hover for tooltip")
-                        .tooltip("This tooltip should appear below the trigger near the top edge."),
+                        .tooltip("This tooltip should appear below the trigger near the top edge.")
+                        .tooltip_placement(Placement::Top),
                 ),
             )
             .child(

website/docs/components/button.md

@@ -307,8 +307,13 @@ Button::new("custom-btn")
 Button::new("btn")
     .label("Hover me")
     .tooltip("This is a helpful tooltip")
+    .tooltip_placement(Placement::Bottom)
 ```
 
+Use `.tooltip_placement(...)` to prefer a side for either `.tooltip(...)` or
+`.tooltip_with_action(...)`. The tooltip still flips when that side does not fit.
+Omit placement to keep automatic positioning.
+
 ### Custom Children
 
 ```rust