Add pop_until_active

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Added `x_axis` and `y_axis` parameters to `Widget.scroll_to_region` https://github.com/Textualize/textual/pull/5047
 - Added `Tree.move_cursor_to_line` https://github.com/Textualize/textual/pull/5052
+- Added `Screen.pop_until_active` https://github.com/Textualize/textual/pull/5069
 
 ### Changed
 

src/textual/app.py

@@ -2634,6 +2634,33 @@ async def do_pop() -> None:
 
         return AwaitComplete(do_pop()).call_next(self)
 
+    def _pop_to_screen(self, screen: Screen) -> None:
+        """Pop screens until the given screen is active.
+
+        Args:
+            screen: desired active screen
+
+        Raises:
+            ScreenError: If the screen doesn't exist in the stack.
+        """
+        screens_to_pop: list[Screen] = []
+        for pop_screen in reversed(self.screen_stack):
+            if pop_screen is not screen:
+                screens_to_pop.append(pop_screen)
+            else:
+                break
+        else:
+            raise ScreenError(f"Screen {screen!r} not in screen stack")
+
+        async def pop_screens() -> None:
+            """Pop any screens in `screens_to_pop`."""
+            with self.batch_update():
+                for screen in screens_to_pop:
+                    await screen.dismiss()
+
+        if screens_to_pop:
+            self.call_later(pop_screens)
+
     def set_focus(self, widget: Widget | None, scroll_visible: bool = True) -> None:
         """Focus (or unfocus) a widget. A focused widget will receive key events first.
 

src/textual/screen.py

@@ -1412,6 +1412,23 @@ def pre_await() -> None:
 
         return await_pop
 
+    def pop_until_active(self) -> None:
+        """Pop any screens on top of this one, until this screen is active.
+
+        Raises:
+            ScreenError: If this screen is not in the current mode.
+
+        """
+        from textual.app import ScreenError
+
+        try:
+            self.app._pop_to_screen(self)
+        except ScreenError:
+            # More specific error message
+            raise ScreenError(
+                f"Can't make {self} active as it is not in the current stack."
+            ) from None
+
     async def action_dismiss(self, result: ScreenResultType | None = None) -> None:
         """A wrapper around [`dismiss`][textual.screen.Screen.dismiss] that can be called as an action.
 

tests/snapshot_tests/test_snapshots.py

@@ -2019,3 +2019,38 @@ def action_toggle_console(self) -> None:
 
     app = MRE()
     assert snap_compare(app, press=["space", "space", "z"])
+
+
+def test_pop_until_active(snap_compare):
+    class BaseScreen(Screen):
+        def compose(self) -> ComposeResult:
+            yield Label("BASE")
+
+    class FooScreen(Screen):
+        def compose(self) -> ComposeResult:
+            yield Label("Foo")
+
+    class BarScreen(Screen):
+        BINDINGS = [("b", "app.make_base_active")]
+
+        def compose(self) -> ComposeResult:
+            yield Label("Bar")
+
+    class PopApp(App):
+        SCREENS = {"base": BaseScreen}
+
+        async def on_mount(self) -> None:
+            # Push base
+            await self.push_screen("base")
+            # Push two screens
+            await self.push_screen(FooScreen())
+            await self.push_screen(BarScreen())
+
+        def action_make_base_active(self) -> None:
+            self.get_screen("base").pop_until_active()
+
+    app = PopApp()
+    # App will push three screens
+    # Pressing "b" will call pop_until_active, and pop two screens
+    # End result should be screen showing "BASE"
+    assert snap_compare(app, press=["b"])