feat: Add pop_until_with_result to Page

[brunobrown]

Description

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

Fixes #6326

Test Code

import asyncio

import flet as ft


def main(page: ft.Page):
    page.title = "pop_until_with_result Example"

    result_text = ft.Text("No result yet", size=18)

    def route_change():
        page.views.clear()
        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 in ["/step1", "/step2"]:
            page.views.append(
                ft.View(
                    route="/step1",
                    controls=[
                        ft.AppBar(title=ft.Text("Step 1"), bgcolor=ft.Colors.SURFACE_BRIGHT),
                        ft.Button(
                            "Go to Step 2",
                            on_click=lambda _: asyncio.create_task(page.push_route("/step2")),
                        ),
                    ],
                )
            )
        if page.route == "/step2":
            page.views.append(
                ft.View(
                    route="/step2",
                    controls=[
                        ft.AppBar(title=ft.Text("Step 2 (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)

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• I signed the CLA.
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• New and existing tests pass locally with my changes
• I have made corresponding changes to the documentation (if applicable)

Screenshots

Additional details

• Flutter reference: Navigator.popUntilWithResult — issue #30112 (79+ reactions, 6 years open)
• No Dart-side changes needed — Python's page.update() syncs the view list and Flutter's Navigator rebuilds with correct transitions automatically
• 12 unit tests covering: event creation, exports, method behavior, edge cases, event firing
• Example app added at examples/apps/routing_navigation/pop_until_with_result.py

Files changed

File	Change
sdk/python/packages/flet/src/flet/controls/page.py	ViewPopResultEvent, pop_until_with_result(), on_view_pop_result, unified before_event
sdk/python/packages/flet/src/flet/__init__.py	Export ViewPopResultEvent
sdk/python/packages/flet/tests/test_pop_until_with_result.py	12 unit tests
sdk/python/examples/apps/routing_navigation/pop_until_with_result.py	Example app
sdk/python/packages/flet/docs/assets/navigation-routing/pop-until-with-result-example.gif	Demo GIF

Summary by Sourcery

Add support for popping multiple views with a result and wire it into page navigation events.

New Features:

• Introduce ViewPopResultEvent to carry navigation results back to the destination view when popping views.
• Add Page.pop_until_with_result() to pop back to a target route while returning a result via on_view_pop_result.
• Expose ViewPopResultEvent from the top-level flet package for direct import.
• Provide an example routing app demonstrating pop_until_with_result usage.

Tests:

• Add unit tests covering ViewPopResultEvent creation, typing, imports, the new on_view_pop_result handler, and pop_until_with_result behavior and edge cases.

[CLAassistant]

All committers have signed the CLA.

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine