feat: Page.pop_views_until() to pop multiple views and return a result to the destination view (#6347)

* 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

* docs: add pop_until_with_result demo GIF

Add animated GIF demonstrating the pop_until_with_result feature
for the navigation-routing documentation assets.

* refactor: rename to pop_views_until, based on feedback from @ndonkoHenri

Rename pop_until_with_result() to pop_views_until(),
on_view_pop_result to on_views_pop_until,
and ViewPopResultEvent to ViewsPopUntilEvent.

Requested by @FeodorFitsner in the PR review.

* test: replace unit tests with integration test for pop_views_until

Remove standalone unit test file and add integration test to
test_routing_navigation.py following the existing test pattern,
as suggested by @ndonkoHenri in PR review.

* fix: use distinct text in SnackBar to avoid duplicate match in integration test

The SnackBar and result_text both contained "Result: Flow completed!",
causing find_by_text to match 2 elements instead of 1 in the CI
integration test.

* fix: align example and test with v0.85.0 directory structure

Convert pop_views_until example from single file to subdirectory
with main.py + pyproject.toml, matching the new example structure
introduced in v0.84.0. Fix flet_app_main references to use
module.main format consistent with upstream.

* docs: add changelog entry for pop_views_until

Add new feature record to CHANGELOG.md for v0.85.0 as required
by the release branch CI check.

* docs: update docstrings to reST cross-refs and fix changelog format

Use :class:, :meth:, :attr: reST roles in docstrings instead of mkdocs-style cross-references, per docs-conventions guidelines.
Remove Flutter reference from pop_views_until docstring.
Fix CHANGELOG author format to plain.

Requested by @ndonkoHenri in PR review.

* docs: add pop_views_until section to navigation and routing page

Add example and description for pop_views_until to the cookbook
navigation-and-routing docs page.

Requested by @ndonkoHenri in PR review.

Author: brunobrown

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * Add `ft.use_dialog()` hook for declarative dialog management from within `@ft.component` functions, with frozen-diff reactive updates and automatic open/close lifecycle ([#6335](https://github.com/flet-dev/flet/pull/6335)) by @FeodorFitsner.
 * Add `scrollable`, `pin_leading_to_top`, and `pin_trailing_to_bottom` properties to `NavigationRail` for scrollable content with optional pinned leading/trailing controls ([#1923](https://github.com/flet-dev/flet/issues/1923), [#6356](https://github.com/flet-dev/flet/pull/6356)) by @ndonkoHenri.
+* Add `Page.pop_views_until()` to pop multiple views and return a result to the destination view ([#6326](https://github.com/flet-dev/flet/issues/6326), [#6347](https://github.com/flet-dev/flet/pull/6347)) by @brunobrown.
 
 ### Improvements
 

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.85.0"
+    version: "0.82.2"
   flet_ads:
     dependency: "direct main"
     description:
@@ -911,18 +911,18 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861
+      sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.19"
+    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: "8161c84903fd860b26bfdefb7963b3f0b68fee7adea0f59ef805ecca346f0c7a"
+      sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.10"
+    version: "0.7.7"
   torch_light:
     dependency: transitive
     description:

sdk/python/examples/apps/routing_navigation/pop_views_until/main.py

@@ -0,0 +1,112 @@
+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_views_until("/", result="Flow completed!")
+                            ),
+                        ),
+                    ],
+                )
+            )
+
+        page.update()
+
+    def on_pop_result(e: ft.ViewsPopUntilEvent):
+        result_text.value = f"Result: {e.result}"
+        page.show_dialog(ft.SnackBar(ft.Text(f"Got 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_views_pop_until = on_pop_result
+
+    route_change()
+
+
+if __name__ == "__main__":
+    ft.run(main)

sdk/python/examples/apps/routing_navigation/pop_views_until/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "apps-routing-navigation-pop-views-until"
+version = "1.0.0"
+description = "Pops multiple views from the navigation stack and returns a result to the destination view."
+requires-python = ">=3.10"
+keywords = ["apps", "routing", "navigation", "pop", "views", "result", "async"]
+authors = [{ name = "Flet team", email = "hello@flet.dev" }]
+dependencies = ["flet"]
+
+[dependency-groups]
+dev = ["flet-cli", "flet-desktop", "flet-web"]
+
+[tool.flet.gallery]
+categories = ["Apps/Navigation"]
+
+[tool.flet.metadata]
+title = "Pop views until"
+controls = ["View", "AppBar", "Button", "Text", "SnackBar"]
+layout_pattern = "multi-step-flow"
+complexity = "intermediate"
+features = ["routing", "view stack", "pop views until", "result passing", "async"]
+
+[tool.flet]
+org = "dev.flet"
+company = "Flet"
+copyright = "Copyright (C) 2023-2026 by Flet"

sdk/python/packages/flet/integration_tests/examples/apps/test_routing_navigation.py

@@ -6,6 +6,7 @@
 from examples.apps.routing_navigation.home_store import main as home_store
 from examples.apps.routing_navigation.initial_route import main as initial_route
 from examples.apps.routing_navigation.pop_view_confirm import main as pop_view_confirm
+from examples.apps.routing_navigation.pop_views_until import main as pop_views_until
 from examples.apps.routing_navigation.route_change_event import (
     main as route_change_event,
 )
@@ -185,3 +186,59 @@ async def test_drawer_navigation(flet_app_function: ftt.FletTestApp):
     # Verify home view
     home_text = await flet_app_function.tester.find_by_text("Welcome to Home Page")
     assert home_text.count == 1
+
+
+@pytest.mark.parametrize(
+    "flet_app_function",
+    [{"flet_app_main": pop_views_until.main}],
+    indirect=True,
+)
+@pytest.mark.asyncio(loop_scope="function")
+async def test_pop_views_until(flet_app_function: ftt.FletTestApp):
+    # Verify initial view
+    button = await flet_app_function.tester.find_by_text_containing("Start flow")
+    assert button.count == 1
+    result_text = await flet_app_function.tester.find_by_text("No result yet")
+    assert result_text.count == 1
+
+    # Navigate to Step 1
+    await flet_app_function.tester.tap(button)
+    await flet_app_function.tester.pump_and_settle()
+    step1_text = await flet_app_function.tester.find_by_text("Step 1 of the flow")
+    assert step1_text.count == 1
+
+    # Navigate to Step 2
+    step2_button = await flet_app_function.tester.find_by_text_containing(
+        "Go to Step 2"
+    )
+    assert step2_button.count == 1
+    await flet_app_function.tester.tap(step2_button)
+    await flet_app_function.tester.pump_and_settle()
+    step2_text = await flet_app_function.tester.find_by_text("Step 2 of the flow")
+    assert step2_text.count == 1
+
+    # Navigate to Step 3
+    step3_button = await flet_app_function.tester.find_by_text_containing(
+        "Go to Step 3"
+    )
+    assert step3_button.count == 1
+    await flet_app_function.tester.tap(step3_button)
+    await flet_app_function.tester.pump_and_settle()
+    final_text = await flet_app_function.tester.find_by_text("Flow complete!")
+    assert final_text.count == 1
+
+    # Click "Finish and go Home" — triggers pop_views_until
+    finish_button = await flet_app_function.tester.find_by_text_containing(
+        "Finish and go Home"
+    )
+    assert finish_button.count == 1
+    await flet_app_function.tester.tap(finish_button)
+    await flet_app_function.tester.pump_and_settle()
+
+    # Verify back at Home with result
+    result_text = await flet_app_function.tester.find_by_text("Result: Flow completed!")
+    assert result_text.count == 1
+
+    # Verify we can start the flow again
+    button = await flet_app_function.tester.find_by_text_containing("Start flow")
+    assert button.count == 1

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

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