feat: Add pop_until_with_result to Page.

Add the Page.pop_until_with_result() method and ViewPopResultEvent to support popping multiple views and returning a result to the destination view — the Flet equivalent of Flutter's Navigator.popUntilWithResult.

Fixes #6326

Author: brunobrown

client/pubspec.lock

@@ -157,10 +157,10 @@ packages:
     dependency: transitive
     description:
       name: characters
-      sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b
+      sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803
       url: "https://pub.dev"
     source: hosted
-    version: "1.4.1"
+    version: "1.4.0"
   charcode:
     dependency: transitive
     description:
@@ -359,7 +359,7 @@ packages:
       path: "../packages/flet"
       relative: true
     source: path
-    version: "0.83.0"
+    version: "0.82.2"
   flet_ads:
     dependency: "direct main"
     description:
@@ -911,18 +911,18 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6"
+      sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.18"
+    version: "0.12.17"
   material_color_utilities:
     dependency: transitive
     description:
       name: material_color_utilities
-      sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b"
+      sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec
       url: "https://pub.dev"
     source: hosted
-    version: "0.13.0"
+    version: "0.11.1"
   media_kit:
     dependency: transitive
     description:
@@ -1628,10 +1628,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636"
+      sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.9"
+    version: "0.7.7"
   torch_light:
     dependency: transitive
     description:

sdk/python/examples/apps/routing_navigation/pop_until_with_result.py

@@ -0,0 +1,114 @@
+import asyncio
+
+import flet as ft
+
+
+def main(page: ft.Page):
+    page.title = "Routes Example"
+
+    result_text = ft.Text("No result yet", size=18)
+
+    def route_change():
+        page.views.clear()
+
+        # Home View (/)
+        page.views.append(
+            ft.View(
+                route="/",
+                controls=[
+                    ft.AppBar(title=ft.Text("Home"), bgcolor=ft.Colors.SURFACE_BRIGHT),
+                    result_text,
+                    ft.Button(
+                        "Start flow",
+                        on_click=lambda _: asyncio.create_task(
+                            page.push_route("/step1")
+                        ),
+                    ),
+                ],
+            )
+        )
+
+        if page.route == "/step1" or page.route == "/step2" or page.route == "/step3":
+            page.views.append(
+                ft.View(
+                    route="/step1",
+                    controls=[
+                        ft.AppBar(
+                            title=ft.Text("Step 1"),
+                            bgcolor=ft.Colors.SURFACE_BRIGHT,
+                        ),
+                        ft.Text("Step 1 of the flow"),
+                        ft.Button(
+                            "Go to Step 2",
+                            on_click=lambda _: asyncio.create_task(
+                                page.push_route("/step2")
+                            ),
+                        ),
+                    ],
+                )
+            )
+
+        if page.route == "/step2" or page.route == "/step3":
+            page.views.append(
+                ft.View(
+                    route="/step2",
+                    controls=[
+                        ft.AppBar(
+                            title=ft.Text("Step 2"),
+                            bgcolor=ft.Colors.SURFACE_BRIGHT,
+                        ),
+                        ft.Text("Step 2 of the flow"),
+                        ft.Button(
+                            "Go to Step 3",
+                            on_click=lambda _: asyncio.create_task(
+                                page.push_route("/step3")
+                            ),
+                        ),
+                    ],
+                )
+            )
+
+        if page.route == "/step3":
+            page.views.append(
+                ft.View(
+                    route="/step3",
+                    controls=[
+                        ft.AppBar(
+                            title=ft.Text("Step 3 (Final)"),
+                            bgcolor=ft.Colors.SURFACE_BRIGHT,
+                        ),
+                        ft.Text("Flow complete!"),
+                        ft.Button(
+                            "Finish and go Home",
+                            on_click=lambda _: asyncio.create_task(
+                                page.pop_until_with_result(
+                                    "/", result="Flow completed!"
+                                )
+                            ),
+                        ),
+                    ],
+                )
+            )
+
+        page.update()
+
+    def on_pop_result(e: ft.ViewPopResultEvent):
+        result_text.value = f"Result: {e.result}"
+        page.show_dialog(ft.SnackBar(ft.Text(f"Result: {e.result}")))
+        page.update()
+
+    async def view_pop(e: ft.ViewPopEvent):
+        if e.view is not None:
+            page.views.remove(e.view)
+            top_view = page.views[-1]
+            await page.push_route(top_view.route)
+
+    page.on_route_change = route_change
+    page.on_view_pop = view_pop
+    page.on_view_pop_result = on_pop_result
+
+    route_change()
+
+
+if __name__ == "__main__":
+    ft.run(main)

sdk/python/packages/flet/src/flet/__init__.py

@@ -409,6 +409,7 @@
     PlatformBrightnessChangeEvent,
     RouteChangeEvent,
     ViewPopEvent,
+    ViewPopResultEvent,
 )
 from flet.controls.painting import (
     Paint,
@@ -1072,6 +1073,7 @@
     "VerticalDivider",
     "View",
     "ViewPopEvent",
+    "ViewPopResultEvent",
     "VisualDensity",
     "Wakelock",
     "WebBrowserName",

sdk/python/packages/flet/src/flet/controls/page.py

@@ -214,6 +214,33 @@ class ViewPopEvent(Event["Page"]):
     """
 
 
+@dataclass
+class ViewPopResultEvent(Event["Page"]):
+    """
+    Event payload delivered when [`Page.pop_until_with_result`]\
+    [flet.Page.pop_until_with_result] completes navigation.
+
+    Carries the result value back to the destination view, analogous to
+    Flutter's `Navigator.popUntilWithResult`.
+    """
+
+    route: str
+    """
+    Route of the destination view that remained on the stack.
+    """
+
+    result: Any = None
+    """
+    The result value passed from the caller of
+    [`pop_until_with_result`][flet.Page.pop_until_with_result].
+    """
+
+    view: Optional[View] = None
+    """
+    Matched [`View`][flet.View] instance for `route`, if found on the page.
+    """
+
+
 @dataclass
 class KeyboardEvent(Event["Page"]):
     """
@@ -505,6 +532,14 @@ class Page(BasePage):
     Called when the user clicks automatic "Back" button in [`AppBar`][flet.] control.
     """
 
+    on_view_pop_result: Optional[EventHandler[ViewPopResultEvent]] = None
+    """
+    Called when [`pop_until_with_result`][flet.Page.pop_until_with_result] reaches
+    the destination view.
+
+    The event carries the result value passed by the caller.
+    """
+
     on_keyboard_event: Optional[EventHandler[KeyboardEvent]] = None
     """
     Called when a keyboard key is pressed.
@@ -706,7 +741,7 @@ def before_event(self, e: ControlEvent):
             self.__last_route = e.route
             self.query()
 
-        elif isinstance(e, ViewPopEvent):
+        elif isinstance(e, ViewPopEvent | ViewPopResultEvent):
             for v in unwrap_component(self.views):
                 v = unwrap_component(v)
                 if v.route == e.route:
@@ -896,6 +931,75 @@ async def view_pop(e):
             arguments={"route": new_route},
         )
 
+    async def pop_until_with_result(self, route: str, result: Any = None) -> None:
+        """
+        Pops views from the navigation stack until a view with the given
+        `route` is found, then delivers `result` via the
+        [`on_view_pop_result`][flet.Page.on_view_pop_result] event.
+
+        This is the Flet equivalent of Flutter's `Navigator.popUntilWithResult`.
+
+        Example:
+            ```python
+            import flet as ft
+
+
+            def main(page: ft.Page):
+                def on_pop_result(e: ft.ViewPopResultEvent):
+                    page.show_dialog(ft.SnackBar(ft.Text(f"Result: {e.result}")))
+
+                page.on_view_pop_result = on_pop_result
+
+                # ... later, from a deeply nested view:
+                async def go_back(ev):
+                    await page.pop_until_with_result("/", result="Done!")
+            ```
+
+        Args:
+            route: Target route to navigate back to. Must match the `route`
+                of an existing [`View`][flet.View] in
+                [`page.views`][flet.Page.views].
+            result: Optional value delivered to
+                [`on_view_pop_result`][flet.Page.on_view_pop_result] on the
+                destination view.
+
+        Raises:
+            ValueError: If no view with the given `route` exists in
+                [`page.views`][flet.Page.views].
+        """
+        views = unwrap_component(self.views)
+
+        # Find the target view (first match from bottom of the stack)
+        target_idx = None
+        for i, v in enumerate(views):
+            v = unwrap_component(v)
+            if v.route == route:
+                target_idx = i
+                break
+
+        if target_idx is None:
+            raise ValueError(f"No view found with route '{route}' in page.views")
+
+        # Remove views above the target
+        del self.views[target_idx + 1 :]
+
+        # Update browser URL
+        await self.push_route(route)
+
+        # Fire on_view_pop_result for the destination view
+        if self.on_view_pop_result:
+            target_view = unwrap_component(views[target_idx])
+            e = ViewPopResultEvent(
+                name="view_pop_result",
+                control=self,
+                route=route,
+                result=result,
+                view=target_view,
+            )
+            await self._trigger_event("view_pop_result", event_data=None, e=e)
+
+        self.update()
+
     def get_upload_url(self, file_name: str, expires: int) -> str:
         """
         Generates presigned upload URL for built-in upload storage: