flet-asp

Flet-ASP - Flet Atomic State Pattern

📖 Overview

Flet-ASP (Flet Atomic State Pattern) is a reactive state management library for Flet, bringing atom-based architecture and separation of concerns into Python apps — inspired by Flutter's Riverpod and ASP.

It provides predictable, testable, and declarative state through:

• Atom – single reactive unit of state
• Selector – derived/computed state
• Action – handles async workflows like login, fetch, etc.

📦 Installation

Install using your package manager of choice:

Pip

pip install flet-asp

Poetry

poetry add flet-asp

UV

uv add flet-asp

📦 Features

✅ Reactive atoms (with controlled mutation)
✅ Selector (sync & async derived values)
✅ Async-safe Actions
✅ One-way and two-way binding (form inputs)
✅ Lightweight and framework-agnostic
✅ Built for Flet

🧪 Example – Basic Counter

import flet as ft
import flet-asp as fa


def main(page: ft.Page):
    state = fa.get_state_manager(page)
    state.atom("count", 0)

    count_ref = ft.Ref[ft.Text]()

    def increment(e):
        state.set("count", state.get("count") + 1)

    page.add(
        ft.Text(ref=count_ref),
        ft.ElevatedButton("Increment", on_click=increment)
    )

    state.bind("count", count_ref)


if __name__ == "__main__":
    ft.app(target=main)

📁 Examples Included

Explore the examples/ folder for full apps:

• 1_counter_atom/
• 2_counter_atom_bind_dynamic/
• 3_computed_fullname/
• 4_action_login/
• 5_selector_user_email/
• 6_listen_user_login/
• 7_bind_two_way_textfield/
• 8_session_reset_clear/
• 9_todo/
• 10_cart_app/

🧩 Design System Ready

Flet-ASP also allows you to create applications following the Atomic Design System, just like Flutter.

Atomic Layer	How Flet-ASP Helps
Atoms	Simple reactive values (e.g., atom("email"), atom("count"), atom("message"), atom("loading")
Selectors	Derived state (e.g., @selector("full_name"), @selector("total_price") or Selector(...))
Actions	Encapsulate side effects (API, auth)
Bindings	bind(), bind_two_way() for full UI ↔ state reactivity
Molecules/Organisms	Combine logic in components
Templates	Reuse UIs across screens

Learn more:

• Atomic Design with Flutter
• Widget Componentization (pt-BR)

🌐 Community

Join the community to contribute or get help:

• Discord
• Report an issue

⭐ Support

If you like this project, please give it a GitHub star and stay tuned for future updates!

🤝🏽 Contributing

Contributions and feedback are welcome!

🔧 How to contribute:

• Fork the repository.
• Create a feature branch.
• Submit a pull request with a detailed explanation of your changes.

💬 How to give feedback:

We value your opinion! Feel free to share suggestions, ideas, or constructive criticism to help improve the project.

• Open an issue.
• Describe the problem or suggestion clearly
• Optionally propose a solution

🕓 Waiting for help?

Be patient — or reach out to the community on Discord for quicker responses.

Commit your work to the LORD, and your plans will succeed. Proverbs 16: 3