Refactor Flet Python declarative API and improve observables

Refactors the Flet Python declarative API to use new hooks and component patterns, replacing StateView with use_state and @ft.component, and updates all examples accordingly. Introduces a new unwrap_component utility, improves Observable and observable collection handling, and adds new public API exports (on_mounted, on_unmounted, on_updated, unwrap_component). Refactors context and session management, updates event and control handling, and fixes various docstrings and type annotations. Removes deprecated code, cleans up hooks, and adds new routing and progress bar examples.

Author: FeodorFitsner

packages/flet/lib/src/controls/page.dart

@@ -164,6 +164,8 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
             pixelRatio: parseDouble(args["pixel_ratio"], _dpr)!);
         final data = await image.toByteData(format: ui.ImageByteFormat.png);
         return data!.buffer.asUint8List();
+      case "push_route":
+        _routeState.route = args["route"];
       default:
         throw Exception("Unknown Page method: $name");
     }
@@ -184,9 +186,7 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
         _multiViews[view.viewId] = MultiView(
             viewId: view.viewId, flutterView: view, initialData: initialData);
         if (triggerAddViewEvent) {
-          widget.control.backend.triggerControlEventById(
-              widget.control.id,
-              "multi_view_add",
+          widget.control.triggerEventWithoutSubscribers("multi_view_add",
               {"view_id": view.viewId, "initial_data": initialData});
         }
         changed = true;
@@ -197,8 +197,8 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
           .any((view) => view.viewId == viewId)) {
         _multiViews.remove(viewId);
         if (triggerAddViewEvent) {
-          widget.control.backend.triggerControlEventById(
-              widget.control.id, "multi_view_remove", viewId);
+          widget.control
+              .triggerEventWithoutSubscribers("multi_view_remove", viewId);
         }
         changed = true;
       }
@@ -218,7 +218,8 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
   }
 
   void _handleAppLifecycleTransition(String state) {
-    widget.control.triggerEvent("app_lifecycle_state_change", {"state": state});
+    widget.control.triggerEventWithoutSubscribers(
+        "app_lifecycle_state_change", {"state": state});
   }
 
   bool _handleKeyDown(KeyEvent e) {
@@ -238,7 +239,7 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
         LogicalKeyboardKey.shiftLeft,
         LogicalKeyboardKey.shiftRight
       ].contains(k)) {
-        widget.control.triggerEvent(
+        widget.control.triggerEventWithoutSubscribers(
             "keyboard_event",
             KeyboardEvent(
                     key: k.keyLabel,
@@ -292,15 +293,6 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
     // clear hrefs index
     FletBackend.of(context).globalKeys.clear();
 
-    // page route
-    var route = widget.control.getString("route");
-    if (route != null && _routeState.route != route) {
-      // update route
-      WidgetsBinding.instance.addPostFrameCallback((_) {
-        _routeState.route = route;
-      });
-    }
-
     if (!widget.control.backend.multiView) {
       // single page mode
       return _buildApp(widget.control, null);
@@ -529,7 +521,7 @@ class _PageControlState extends State<PageControl> with WidgetsBindingObserver {
         pages: pages,
         onDidRemovePage: (page) {
           if (page.key != null) {
-            widget.control.triggerEvent(
+            widget.control.triggerEventWithoutSubscribers(
                 "view_pop", {"route": (page.key as ValueKey).value});
           }
         });

packages/flet/lib/src/flet_backend.dart

@@ -187,22 +187,22 @@ class FletBackend extends ChangeNotifier {
         Message(
             action: MessageAction.registerClient,
             payload: RegisterClientRequestBody(
-                sessionId: SessionStore.getSessionId(pageUri.toString()),
+                sessionId: SessionStore.getSessionId(),
                 pageName: getWebPageName(pageUri),
                 page: {
-                  'route': page.get("route"),
-                  'pwa': page.get("pwa"),
-                  'web': page.get("web"),
-                  'debug': page.get("debug"),
-                  'wasm': page.get("wasm"),
-                  'test': page.get("test"),
-                  'multi_view': page.get("multi_view"),
-                  'platform_brightness': page.get("platform_brightness"),
-                  'width': page.get("width"),
-                  'height': page.get("height"),
-                  'platform': page.get("platform"),
-                  'window': page.child("window")!.toMap(),
-                  'media': page.get("media"),
+                  "route": page.get("route"),
+                  "pwa": page.get("pwa"),
+                  "web": page.get("web"),
+                  "debug": page.get("debug"),
+                  "wasm": page.get("wasm"),
+                  "test": page.get("test"),
+                  "multi_view": page.get("multi_view"),
+                  "platform_brightness": page.get("platform_brightness"),
+                  "width": page.get("width"),
+                  "height": page.get("height"),
+                  "platform": page.get("platform"),
+                  "window": page.child("window")!.toMap(),
+                  "media": page.get("media"),
                 }).toMap()),
         unbuffered: true);
   }
@@ -211,7 +211,7 @@ class FletBackend extends ChangeNotifier {
     if (resp.error?.isEmpty ?? true) {
       // all good!
       // store session ID in a cookie
-      SessionStore.setSessionId(pageUri.toString(), resp.sessionId);
+      SessionStore.setSessionId(resp.sessionId);
       isLoading = false;
       _reconnectDelayMs = 0;
       error = "";
@@ -337,7 +337,8 @@ class FletBackend extends ChangeNotifier {
     debugPrint("Platform brightness updated: $newBrightness");
     platformBrightness = newBrightness;
     updateControl(page.id, {"platform_brightness": newBrightness.name});
-    triggerControlEvent(page, "platform_brightness_change", newBrightness.name);
+    triggerControlEventById(
+        page.id, "platform_brightness_change", newBrightness.name);
     notifyListeners();
   }
 

packages/flet/lib/src/models/control.dart

@@ -149,6 +149,17 @@ class Control extends ChangeNotifier {
     return backend.triggerControlEvent(this, eventName, data);
   }
 
+  /// Triggers a control event without checking for subscribers.
+  ///
+  /// This method directly triggers the event for the control identified by its
+  /// [id] without verifying if there are any subscribers for the event.
+  ///
+  /// - [eventName]: The name of the event to trigger.
+  /// - [data]: Optional data to pass along with the event.
+  void triggerEventWithoutSubscribers(String eventName, [dynamic data]) {
+    return backend.triggerControlEventById(id, eventName, data);
+  }
+
   /// Updates the properties of this control.
   ///
   /// The [props] map contains key-value pairs where the key is the property

packages/flet/lib/src/utils/session_store_non_web.dart

@@ -3,11 +3,11 @@ import 'package:flutter/foundation.dart';
 class SessionStore {
   static String? sessionId;
 
-  static String? getSessionId(String pageUrl) {
+  static String? getSessionId() {
     return get("sessionId");
   }
 
-  static setSessionId(String pageUrl, String? value) {
+  static setSessionId(String? value) {
     set("sessionId", value ?? "");
   }
 

packages/flet/lib/src/utils/session_store_web.dart

@@ -4,12 +4,12 @@ import 'package:web/web.dart' as web;
 const String _sessionIdKey = "_flet_session_id";
 
 class SessionStore {
-  static String? getSessionId(String pageUrl) {
-    return get("$pageUrl$_sessionIdKey");
+  static String? getSessionId() {
+    return get(_sessionIdKey);
   }
 
-  static setSessionId(String pageUrl, String? value) {
-    set("$pageUrl$_sessionIdKey", value ?? "");
+  static setSessionId(String? value) {
+    set(_sessionIdKey, value ?? "");
   }
 
   static String? get(String name) {

sdk/python/examples/apps/declarative/counter.py

@@ -4,32 +4,32 @@
 
 
 @dataclass
+@ft.observable
 class AppState:
     count: int
 
     def increment(self):
         self.count += 1
 
 
-def main(page: ft.Page):
-    state = AppState(count=0)
+@ft.component
+def App():
+    state, _ = ft.use_state(AppState(count=0))
 
-    page.floating_action_button = ft.FloatingActionButton(
-        icon=ft.Icons.ADD, on_click=state.increment
-    )
-    page.add(
-        ft.StateView(
-            state,
-            lambda state: ft.SafeArea(
+    return ft.View(
+        floating_action_button=ft.FloatingActionButton(
+            icon=ft.Icons.ADD, on_click=state.increment
+        ),
+        controls=[
+            ft.SafeArea(
                 ft.Container(
                     ft.Text(value=f"{state.count}", size=50),
                     alignment=ft.Alignment.CENTER,
                 ),
                 expand=True,
-            ),
-            expand=True,
-        )
+            )
+        ],
     )
 
 
-ft.run(main)
+ft.run(lambda page: page.render_views(App))

sdk/python/examples/apps/declarative/edit-form.py

@@ -5,6 +5,7 @@
 
 
 @dataclass
+@ft.observable
 class Form:
     first_name: str = ""
     last_name: str = ""
@@ -15,7 +16,7 @@ def set_first_name(self, value):
     def set_last_name(self, value):
         self.last_name = value
 
-    async def submit(self, e: ft.ControlEvent):
+    async def submit(self, e: ft.Event[ft.Button]):
         e.page.show_dialog(
             ft.AlertDialog(
                 title="Hello",
@@ -28,37 +29,31 @@ async def reset(self):
         self.last_name = ""
 
 
-def main(page: ft.Page):
-    form = Form()
-
-    page.add(
-        ft.StateView(
-            form,
-            lambda state: ft.Column(
-                cast(
-                    list[ft.Control],
-                    [
-                        ft.TextField(
-                            label="First name",
-                            value=form.first_name,
-                            on_change=lambda e: form.set_first_name(e.control.value),
-                        ),
-                        ft.TextField(
-                            label="Last name",
-                            value=form.last_name,
-                            on_change=lambda e: form.set_last_name(e.control.value),
-                        ),
-                        ft.Row(
-                            [
-                                ft.FilledButton("Submit", on_click=form.submit),
-                                ft.FilledTonalButton("Reset", on_click=form.reset),
-                            ]
-                        ),
-                    ],
-                )
-            ),
-        )
-    )
+@ft.component
+def App():
+    form, _ = ft.use_state(Form())
+
+    return [
+        ft.TextField(
+            label="First name",
+            value=form.first_name,
+            on_change=lambda e: form.set_first_name(e.control.value),
+        ),
+        ft.TextField(
+            label="Last name",
+            value=form.last_name,
+            on_change=lambda e: form.set_last_name(e.control.value),
+        ),
+        ft.Row(
+            cast(
+                list[ft.Control],
+                [
+                    ft.FilledButton("Submit", on_click=form.submit),
+                    ft.FilledTonalButton("Reset", on_click=form.reset),
+                ],
+            )
+        ),
+    ]
 
 
-ft.run(main)
+ft.run(lambda page: page.render(App))

sdk/python/examples/apps/declarative/progress-bar.py

@@ -0,0 +1,29 @@
+import asyncio
+from dataclasses import dataclass
+
+import flet as ft
+
+
+@dataclass
+@ft.observable
+class AppState:
+    counter: float
+
+    async def start_counter(self):
+        self.counter = 0
+        for _ in range(0, 10):
+            self.counter += 0.1
+            await asyncio.sleep(0.5)
+
+
+@ft.component
+def App():
+    state, _ = ft.use_state(AppState(counter=0))
+
+    return [
+        ft.ProgressBar(state.counter),
+        ft.Button("Run!", on_click=state.start_counter),
+    ]
+
+
+ft.run(lambda page: page.render(App))