Imperative → Declarative (Flet Python)

Port an existing imperative Flet app to “components mode” with @ft.component, hooks, and (optionally) @ft.observable models.

Outcomes

• Original folder unchanged; new sibling folder created.
• Entry point uses page.render(App) (components mode).
• UI is derived from state; minimal/zero manual page.update() for normal UI updates.

Choose a state strategy

• Use `@ft.observable` for nested app data you mutate in place (boards/lists/cards, drag+drop reorder).
• Use `ft.use_state` for local ephemeral UI state (hover flags, input text, dialog selection).
• Avoid storing live Control/component objects in state; store ids/enums and create controls during render.

Workflow

1) Create a new declarative copy

• Copy the existing app folder to a new one (e.g. trolli → trolli-declarative-*).
• Keep assets/ with the new folder.

2) Switch to components mode entrypoint

• Create a root component @ft.component def App(): ....
• Run with:
• ft.run(lambda page: page.render(App), assets_dir=...)
• Set page globals either:
• in a main(page) function before page.render(App), or
• in ft.on_mounted(...) (works, but ordering can be less obvious).

3) Centralize routing in App

• Keep app.route: str as source of truth.
• In one place, define:
• route_change(e) to normalize/redirect/validate routes and set app.route
• a render-time match app.route (or a derived active_screen) to pick content
• Prefer: route_change mutates route state; App() render chooses UI based on that state.

4) Componentize UI

• Move UI chunks into src/components/*.py.
• Each component:
• takes only the model(s) it needs
• uses hooks for local UI state
• mutates observable models for app data changes

5) Dialogs: reduce page.update() usage

If a dialog mutates existing controls and calls page.update(), convert it to:

• @ft.component dialog content with ft.use_state for error, selected_color, etc.
• event handlers call setters (no explicit updates)
• show it via page.show_dialog(ft.AlertDialog(content=DialogContent(...)))

6) Assets/fonts checklist

• Prefer an absolute assets_dir derived from __file__.
• If running via flet run, be aware it can set FLET_ASSETS_DIR and override assets_dir=.
• Font registration uses the dict key as the font family name:
• page.fonts = {"Pacifico": "Pacifico-Regular.ttf"}
• use font_family="Pacifico".

Common pitfalls (and fixes)

• Event handler typing is invariant (Event[Sub] ≠ Event[Base]):
• If on_click is declared on Button, annotate e as ft.Event[ft.Button] (or use def handler(): ...).
• `TemplateRoute` params are dynamic:
• raw = getattr(troute, "id", None) then isinstance(raw, str) before int(raw).
• *`controls=[[...], ...]` can confuse type checkers** with components:
• build lists in two steps and annotate/cast, or return raw controls from non-component factories.