Add shared overlay focus restoration

Author: xoofx

site/docs/controls/commandpalette.md

@@ -52,10 +52,13 @@ When open:
 - Press Down from the search box to move directly to the next result
 - Resize or drag the palette window with the mouse
 - Press Esc to close
+- Closing the palette returns focus to the control that was focused before `Show()`
 
 ## Host chrome
 
-When displayed via `CommandPalette.Show()`, the palette is hosted inside a resizable dialog window. You can still wrap the palette content with a template visual using `CommandPaletteStyle`:
+When displayed via `CommandPalette.Show()`, the palette is hosted inside a resizable dialog window. The host dialog takes
+care of restoring the previous focus when the palette closes. You can still wrap the palette content with a template visual
+using `CommandPaletteStyle`:
 
 ```csharp
 using XenoAtom.Terminal.UI.Controls;

site/docs/controls/dialog.md

@@ -14,6 +14,7 @@ title: Dialog
 Dialogs are displayed in fullscreen apps and typically:
 
 - take focus when shown
+- restore the previously focused control when closed
 - can be modal or non-modal depending on configuration
 - can be moved by dragging the top border row
 - highlights the top border row on hover so the move affordance is visible
@@ -29,6 +30,7 @@ Dialogs are displayed in fullscreen apps and typically:
 - `TopRightText`, `BottomLeftText`, and `BottomRightText` let you decorate the dialog border the same way `Group` does.
 - `DialogStyle` lets you override border glyphs, surface/border styles, label cutout styling, and the hover styling used for resize handles and the move bar.
 - Top and bottom hover affordances respect border-label cutouts so the highlight does not paint over those visuals.
+- Focus restoration is automatic, so showing a dialog does not require manual save/restore focus code in callers.
 
 ```csharp
 var dialog = new Dialog()

site/docs/controls/popup.md

@@ -34,10 +34,11 @@ Popups participate in focus. Common dismissal patterns:
 - close on `Escape`,
 - close when clicking outside,
 - close when the popup loses focus (for transient UI).
+- restore the previously focused control when the popup closes.
 
 > [!IMPORTANT]
-> When you show a popup from a control, keep the focus rules explicit: decide whether focus should move into the popup
-> (typical for menus) or remain on the originating control (typical for passive tooltips).
+> Interactive popups save the currently focused control when shown and restore it on close. This keeps dropdowns,
+> context menus, search popups, and similar overlays consistent without each caller having to manage focus manually.
 
 ## Defaults
 

site/docs/input.md

@@ -54,6 +54,7 @@ Controls opt in to focus by setting `Focusable = true`.
 - Keyboard focus is kept within a focus scope managed by `TerminalApp`.
 - On mouse down (or double click), `TerminalApp` walks up from the hit target to the nearest focusable ancestor and focuses it.
   - This is why clicking inside a complex control (like a text editor) typically focuses that editor.
+- `Popup` and `Dialog` automatically save the previously focused control when shown and restore it when closed.
 
 If you implement a focusable control, use `HasFocus` / `HasFocusWithin` to render focus cues and to decide what keyboard behavior to enable.
 

site/docs/readme.md

@@ -50,7 +50,7 @@ See also:
 - [Data Templating](data-templating.md) (DataTemplates, DataPresenter<T>, item templates)
 - [Culture](culture.md) (culture-aware value formatting)
 - [Layout](layout.md) (layout protocol, alignment, margin/padding)
-- [Input](input.md) (keyboard/mouse, focus, routed events, capture)
+- [Input](input.md) (keyboard/mouse, focus scopes, overlay focus restore, routed events, capture)
 - [Commands](commands.md) (commands, key sequences, key hints with CommandBar)
 - [Styling](styling.md) (Theme, styles, environment, brushes/gradients)
 - [Rendering](rendering.md) (cell buffer, diff renderer, performance)

src/XenoAtom.Terminal.UI.Tests/CommandPaletteTests.cs

@@ -406,6 +406,39 @@ public void CommandPalette_Restores_Focus_On_Close()
         Assert.AreSame(focusedBefore, driver.App.FocusedElement);
     }
 
+    [TestMethod]
+    public void CommandPalette_Escape_Restores_Exact_Previous_Focus()
+    {
+        var first = new TextBox("First");
+        var second = new TextBox("Second");
+        var palette = new CommandPalette();
+        var root = new VStack(first, second);
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(80, 16));
+        driver.Tick();
+
+        driver.App.Focus(second);
+        driver.Tick();
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.open",
+            LabelMarkup = "Open",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        palette.Show();
+        driver.Tick();
+
+        Assert.IsInstanceOfType(driver.App.FocusedElement, typeof(TextBox), "Expected the palette search box to take focus.");
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.Tick();
+
+        Assert.AreSame(second, driver.App.FocusedElement);
+    }
+
     [TestMethod]
     public void CommandPalette_Ranks_Word_Boundary_Matches_Ahead_Of_Later_Matches()
     {

src/XenoAtom.Terminal.UI.Tests/OverlayFocusRestoreTests.cs

@@ -0,0 +1,126 @@
+// Copyright (c) Alexandre Mutel. All rights reserved.
+// Licensed under the BSD-Clause 2 license.
+// See license.txt file in the project root for full license information.
+
+using XenoAtom.Terminal.UI.Controls;
+using XenoAtom.Terminal.UI.Hosting;
+
+namespace XenoAtom.Terminal.UI.Tests;
+
+[TestClass]
+public sealed class OverlayFocusRestoreTests
+{
+    [TestMethod]
+    public void Popup_Close_Restores_Previous_Focus()
+    {
+        var focusedBefore = new TextBox("Before");
+        var anchor = new Button("Anchor");
+        var popupFocus = new TextBox("Popup");
+        var root = new VStack(focusedBefore, anchor, new TextBox("After"));
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen);
+        driver.Tick();
+
+        driver.App.Focus(focusedBefore);
+        driver.Tick();
+
+        var popup = new Popup
+        {
+            Anchor = anchor,
+            Content = popupFocus,
+            MatchAnchorWidth = false,
+        };
+
+        popup.Show();
+        driver.Tick();
+
+        Assert.AreSame(popupFocus, driver.App.FocusedElement);
+
+        popup.Close();
+        driver.Tick();
+
+        Assert.AreSame(focusedBefore, driver.App.FocusedElement);
+    }
+
+    [TestMethod]
+    public void Dialog_Close_Restores_Previous_Focus()
+    {
+        var focusedBefore = new TextBox("Before");
+        var dialogFocus = new TextBox("Dialog");
+        var root = new VStack(focusedBefore, new TextBox("After"));
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen);
+        driver.Tick();
+
+        driver.App.Focus(focusedBefore);
+        driver.Tick();
+
+        var dialog = new Dialog
+        {
+            IsModal = true,
+            Width = 20,
+            Height = 6,
+            Content = dialogFocus,
+        };
+
+        dialog.Show();
+        driver.Tick();
+
+        Assert.AreSame(dialogFocus, driver.App.FocusedElement);
+
+        dialog.Close();
+        driver.Tick();
+
+        Assert.AreSame(focusedBefore, driver.App.FocusedElement);
+    }
+
+    [TestMethod]
+    public void Nested_Overlays_Restore_Focus_Per_Level()
+    {
+        var focusedBefore = new TextBox("Before");
+        var dialogFocus = new TextBox("Dialog");
+        var popupFocus = new TextBox("Popup");
+        var root = new VStack(focusedBefore, new TextBox("After"));
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen);
+        driver.Tick();
+
+        driver.App.Focus(focusedBefore);
+        driver.Tick();
+
+        var dialog = new Dialog
+        {
+            IsModal = true,
+            Width = 20,
+            Height = 6,
+            Content = dialogFocus,
+        };
+
+        dialog.Show();
+        driver.Tick();
+
+        Assert.AreSame(dialogFocus, driver.App.FocusedElement);
+
+        var popup = new Popup
+        {
+            Anchor = dialogFocus,
+            Content = popupFocus,
+            MatchAnchorWidth = false,
+        };
+
+        popup.Show();
+        driver.Tick();
+
+        Assert.AreSame(popupFocus, driver.App.FocusedElement);
+
+        popup.Close();
+        driver.Tick();
+
+        Assert.AreSame(dialogFocus, driver.App.FocusedElement);
+
+        dialog.Close();
+        driver.Tick();
+
+        Assert.AreSame(focusedBefore, driver.App.FocusedElement);
+    }
+}

src/XenoAtom.Terminal.UI.Tests/TextAreaSearchReplaceTests.cs

@@ -132,6 +132,27 @@ public void TextArea_Closing_Find_Popup_Clears_Search_Query()
         Assert.AreEqual("No search", target.GetStatusText(), "Closing the find popup should clear match highlighting.");
     }
 
+    [TestMethod]
+    public void TextArea_SearchReplace_Popup_Restores_Focus_After_Mode_Toggle_And_Close()
+    {
+        var editor = new TextArea("foo bar foo");
+        using var driver = new TerminalAppTestDriver(editor, TerminalHostKind.Fullscreen, new TerminalSize(60, 10));
+        driver.Tick();
+
+        Assert.AreSame(editor, driver.App.FocusedElement);
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Unknown, Char = TerminalChar.CtrlF, Modifiers = TerminalModifiers.Ctrl });
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Unknown, Char = TerminalChar.CtrlH, Modifiers = TerminalModifiers.Ctrl });
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.Tick();
+
+        Assert.AreSame(editor, driver.App.FocusedElement);
+    }
+
     [TestMethod]
     public void TextArea_ReplaceAll_Updates_Document_Text()
     {

src/XenoAtom.Terminal.UI/Controls/CommandPalette.cs

@@ -138,7 +138,7 @@ public void Show()
         EnsureHostGeometry(app.Root.Bounds, style);
         InvalidateResults();
 
-        app.ShowWindow(_hostDialog);
+        _hostDialog.Show();
         app.Post(RealignHostDialog);
         app.Post(FocusSearch);
     }
@@ -153,16 +153,24 @@ public void Close()
             return;
         }
 
+        if (_hostDialog.Parent is null)
+        {
+            _hostDialog.Content = null;
+            _hostGeometryInitialized = false;
+            _focusContext = null;
+            return;
+        }
+
         var app = App ?? _hostDialog.App ?? Dispatcher.AttachedApp;
-        if (app is null || _hostDialog.Parent is null)
+        if (app is null)
         {
             return;
         }
 
-        app.CloseWindow(_hostDialog);
+        _hostDialog.Close();
         _hostDialog?.Content = null;
         _hostGeometryInitialized = false;
-        RestoreFocus();
+        _focusContext = null;
     }
 
     /// <inheritdoc />
@@ -319,22 +327,6 @@ private void RealignHostDialog()
         _hostDialog.Arrange(app.Root.Bounds);
     }
 
-    private void RestoreFocus()
-    {
-        var app = App ?? _hostDialog?.App ?? Dispatcher.AttachedApp;
-        if (app is null)
-        {
-            return;
-        }
-
-        if (_focusContext is not null && ReferenceEquals(_focusContext.App, app))
-        {
-            app.Focus(_focusContext);
-        }
-
-        _focusContext = null;
-    }
-
     private bool IsAttachedToHostDialog()
     {
         if (_hostDialog is null || _hostDialog.Parent is null)

src/XenoAtom.Terminal.UI/Controls/ContextMenuService.cs

@@ -552,7 +552,6 @@ private void CloseSelf()
             if (popup is not null)
             {
                 popup.Close();
-                _rootPopup.App?.Focus(_parent);
             }
         }