flet-asp 0.2.1

Flet-ASP – The Flet Atomic State Pattern is a reactive state management library for Flet.

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

---

✨ Key Features

✅ Reactive atoms - Automatic UI updates when state changes
✅ Selectors - Derived/computed state (sync & async)
✅ Actions - Async-safe workflows for API calls, auth, etc.
✅ One-way & two-way binding - Seamless form input synchronization
✅ Hybrid update strategy - Bindings work even before controls are mounted
✅ Python 3.14+ optimizations - Free-threading, incremental GC, 3-5% faster
✅ Lightweight - No dependencies beyond Flet
✅ Type-safe - Full type hints support

---

🚀 Quick Start

1. Basic Counter (Your First Atom)

The simplest way to use Flet-ASP: create an atom, bind it to a control, and update it.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    # Initialize state manager
    fa.get_state_manager(page)

    # Create a reactive atom
    page.state.atom("count", 0)

    # Create UI references
    count_text = ft.Ref[ft.Text]()

    def increment(e):
        # Update the atom - UI updates automatically!
        current = page.state.get("count")
        page.state.set("count", current + 1)

    # Build UI
    page.add(
        ft.Column([
            ft.Text("Counter", size=30),
            ft.Text(ref=count_text, size=50),
            ft.ElevatedButton("Increment", on_click=increment)
        ])
    )

    # Bind atom to UI - the Text will update automatically
    page.state.bind("count", count_text)

ft.app(target=main)

What's happening here?

1. atom("count", 0) - Creates a reactive piece of state
2. bind("count", count_text) - Connects state to UI
3. set("count", value) - Updates state → UI updates automatically!

---

2. Form with Two-Way Binding

Perfect for input fields that need to sync with state.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Create atoms for form fields
    page.state.atom("email", "")
    page.state.atom("password", "")

    # UI references
    email_field = ft.Ref[ft.TextField]()
    password_field = ft.Ref[ft.TextField]()
    message_text = ft.Ref[ft.Text]()

    def login(e):
        email = page.state.get("email")
        password = page.state.get("password")

        if email == "[e-mail]" and password == "123":
            message_text.current.value = f"Welcome, {email}!"
        else:
            message_text.current.value = "Invalid credentials"
        page.update()

    page.add(
        ft.Column([
            ft.Text("Login Form", size=24),
            ft.TextField(ref=email_field, label="Email"),
            ft.TextField(ref=password_field, label="Password", password=True),
            ft.ElevatedButton("Login", on_click=login),
            ft.Text(ref=message_text)
        ])
    )

    # Two-way binding: TextField ↔ Atom
    page.state.bind_two_way("email", email_field)
    page.state.bind_two_way("password", password_field)

ft.app(target=main)

Key concept: bind_two_way() keeps the TextField and atom in perfect sync!

---

3. Computed State with Selectors

Derive new values from existing state automatically.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Base atoms
    page.state.atom("first_name", "John")
    page.state.atom("last_name", "Doe")

    # Computed state - automatically recalculates when dependencies change
    @page.state.selector("full_name")
    def compute_full_name(get):
        return f"{get('first_name')} {get('last_name')}"

    # UI
    first_field = ft.Ref[ft.TextField]()
    last_field = ft.Ref[ft.TextField]()
    full_name_text = ft.Ref[ft.Text]()

    page.add(
        ft.Column([
            ft.Text("Name Builder", size=24),
            ft.TextField(ref=first_field, label="First Name"),
            ft.TextField(ref=last_field, label="Last Name"),
            ft.Divider(),
            ft.Text("Full Name:", weight=ft.FontWeight.BOLD),
            ft.Text(ref=full_name_text, size=20, color=ft.Colors.BLUE)
        ])
    )

    # Bind inputs
    page.state.bind_two_way("first_name", first_field)
    page.state.bind_two_way("last_name", last_field)

    # Bind computed state
    page.state.bind("full_name", full_name_text)

ft.app(target=main)

Magic! The full name updates automatically when first or last name changes.

---

4. Async Operations with Actions

Handle API calls, async operations, and side effects cleanly.

import asyncio
import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    page.state.atom("user", None)
    page.state.atom("loading", False)

    # Define async action
    async def login_action(get, set_value, params):
        set_value("loading", True)

        # Simulate API call
        await asyncio.sleep(2)

        # Validate credentials
        email = params.get("email")
        password = params.get("password")

        if email == "[e-mail]" and password == "123":
            set_value("user", {"email": email, "name": "Test User"})
        else:
            set_value("user", None)

        set_value("loading", False)

    # Create action
    login = fa.Action(login_action)

    # UI
    email_field = ft.Ref[ft.TextField]()
    password_field = ft.Ref[ft.TextField]()
    status_text = ft.Ref[ft.Text]()

    async def handle_login(e):
        await login.run_async(
            page.state,
            {
                "email": email_field.current.value,
                "password": password_field.current.value
            }
        )

        user = page.state.get("user")
        if user:
            status_text.current.value = f"Welcome, {user['name']}!"
        else:
            status_text.current.value = "Login failed"
        page.update()

    # Listen to loading state
    def on_loading_change(is_loading):
        status_text.current.value = "Logging in..." if is_loading else ""
        page.update()

    page.state.listen("loading", on_loading_change)

    page.add(
        ft.Column([
            ft.Text("Async Login", size=24),
            ft.TextField(ref=email_field, label="Email"),
            ft.TextField(ref=password_field, label="Password", password=True),
            ft.ElevatedButton("Login", on_click=handle_login),
            ft.Text(ref=status_text)
        ])
    )

ft.app(target=main)

Actions encapsulate complex async logic in a testable, reusable way.

---

📚 Advanced Usage

Custom Controls with Reactive State

Create reusable components with encapsulated state.

import flet as ft
import flet_asp as fa

class Counter(ft.Column):
    """Reusable counter component with its own state."""

    def __init__(self, page: ft.Page, counter_id: str, title: str):
        super().__init__()
        self.page = page
        self.counter_id = counter_id
        self.value_text = ft.Ref[ft.Text]()

        # Initialize state for this counter
        page.state.atom(f"{counter_id}_count", 0)

        self.controls = [
            ft.Container(
                content=ft.Column([
                    ft.Text(title, size=20, weight=ft.FontWeight.BOLD),
                    ft.Text(ref=self.value_text, size=40, color=ft.Colors.BLUE),
                    ft.Row([
                        ft.IconButton(
                            icon=ft.Icons.REMOVE,
                            on_click=self.decrement
                        ),
                        ft.IconButton(
                            icon=ft.Icons.ADD,
                            on_click=self.increment
                        )
                    ], alignment=ft.MainAxisAlignment.CENTER)
                ], horizontal_alignment=ft.CrossAxisAlignment.CENTER),
                padding=20,
                border=ft.border.all(2, ft.Colors.BLUE),
                border_radius=10
            )
        ]

    def did_mount(self):
        # Bind when component is mounted
        self.page.state.bind(f"{self.counter_id}_count", self.value_text)

    def increment(self, e):
        current = self.page.state.get(f"{self.counter_id}_count")
        self.page.state.set(f"{self.counter_id}_count", current + 1)

    def decrement(self, e):
        current = self.page.state.get(f"{self.counter_id}_count")
        self.page.state.set(f"{self.counter_id}_count", current - 1)

def main(page: ft.Page):
    fa.get_state_manager(page)

    page.add(
        ft.Column([
            ft.Text("Multiple Counters", size=30),
            ft.Row([
                Counter(page, "counter1", "Counter A"),
                Counter(page, "counter2", "Counter B"),
                Counter(page, "counter3", "Counter C")
            ])
        ])
    )

ft.app(target=main)

---

Navigation with State Preservation

State persists across navigation automatically!

import flet as ft
import flet_asp as fa

def home_screen(page: ft.Page):
    """Home screen with shared state."""
    count_text = ft.Ref[ft.Text]()

    def go_to_settings(e):
        page.views.clear()
        page.views.append(settings_screen(page))
        page.update()

    return ft.View(
        "/",
        [
            ft.AppBar(title=ft.Text("Home"), bgcolor=ft.Colors.BLUE),
            ft.Column([
                ft.Text("Counter Value:", size=20),
                ft.Text(ref=count_text, size=50, color=ft.Colors.BLUE),
                ft.ElevatedButton("Go to Settings", on_click=go_to_settings)
            ])
        ]
    )

def settings_screen(page: ft.Page):
    """Settings screen - modifies shared state."""

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

    def go_back(e):
        page.views.clear()
        page.views.append(home_screen(page))
        page.update()

    return ft.View(
        "/settings",
        [
            ft.AppBar(title=ft.Text("Settings"), bgcolor=ft.Colors.GREEN),
            ft.Column([
                ft.Text("Modify Counter", size=20),
                ft.ElevatedButton("Increment", on_click=increment),
                ft.ElevatedButton("Go Back", on_click=go_back)
            ])
        ]
    )

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Shared state across screens
    page.state.atom("count", 0)

    page.views.append(home_screen(page))

    # Bind state after adding view (works with hybrid strategy!)
    count_ref = page.views[0].controls[1].controls[1]  # Get the count text
    page.state.bind("count", ft.Ref[ft.Text]())

ft.app(target=main)

---

Global State Outside Page Scope

For advanced scenarios like testing, multi-window applications, or complex state architectures, you can create a StateManager outside the page scope.

import flet as ft
import flet_asp as fa

# Create global StateManager OUTSIDE the page
global_state = fa.StateManager()

def screen_a(page: ft.Page):
    """Main screen with counter."""
    count_ref = ft.Ref[ft.Text]()

    def increment(e):
        # Use global_state instead of page.state
        global_state.set("count", global_state.get("count") + 1)

    def go_to_b(e):
        page.go("/b")

    view = ft.View(
        "/",
        [
            ft.Text("Screen A - Global State", size=24, weight=ft.FontWeight.BOLD),
            ft.Text(ref=count_ref, size=40, color=ft.Colors.BLUE_700),
            ft.ElevatedButton("Increment", on_click=increment),
            ft.ElevatedButton("Go to Screen B", on_click=go_to_b),
        ],
        padding=20,
    )

    # Bind using global_state
    global_state.bind("count", count_ref)
    return view

def screen_b(page: ft.Page):
    """Secondary screen displaying the counter."""
    def go_back(e):
        page.go("/")

    return ft.View(
        "/b",
        [
            ft.Text("Screen B - Global State", size=24, weight=ft.FontWeight.BOLD),
            ft.Text(f"Counter value: {global_state.get('count')}", size=16),
            ft.Text("State is managed globally!", color=ft.Colors.GREEN_700),
            ft.ElevatedButton("Go back", on_click=go_back),
        ],
        padding=20,
    )

def main(page: ft.Page):
    """App entry point."""
    # IMPORTANT: Attach the page to the global StateManager
    global_state.page = page

    # Initialize atoms
    global_state.atom("count", 0)

    def route_change(e):
        page.views.clear()
        if page.route == "/b":
            page.views.append(screen_b(page))
        else:
            page.views.append(screen_a(page))
        page.update()

    page.on_route_change = route_change
    page.go("/")

ft.app(target=main)

When to use global state:

Use Case	Why Global State?
Unit Testing	Test state logic without creating a Flet page
Multi-Window Apps	Share state between multiple page instances
Advanced Architectures	State exists independently of UI lifecycle
Framework Integration	Flet-ASP as part of a larger system

Key differences:

Aspect	page.state	global_state
Creation	fa.get_state_manager(page)	fa.StateManager()
Page binding	Automatic	Manual (global_state.page = page)
Scope	Inside main()	Global (module level)
Lifecycle	Managed by page	Manual
When to use	✅ Most cases	⚠️ Specific scenarios

Common pitfalls:

# ❌ WRONG - Forgot to attach page
global_state = fa.StateManager()

def main(page: ft.Page):
    global_state.atom("count", 0)  # Error: page not attached!

# ✅ CORRECT - Attach page first
global_state = fa.StateManager()

def main(page: ft.Page):
    global_state.page = page  # Attach first!
    global_state.atom("count", 0)

Testing example:

import unittest
import flet_asp as fa

# Global state for testing
test_state = fa.StateManager()

class TestMyLogic(unittest.TestCase):
    def setUp(self):
        test_state._atoms.clear()
        test_state.atom("count", 0)

    def test_increment(self):
        # Test logic without creating a Flet page
        test_state.set("count", test_state.get("count") + 1)
        self.assertEqual(test_state.get("count"), 1)

    def test_computed_value(self):
        test_state.atom("double", lambda: test_state.get("count") * 2)
        test_state.set("count", 5)
        self.assertEqual(test_state.get("double"), 10)

For a complete example, see 11.1_global_state_outside.py.

---

Complex Selectors with Async Data

Fetch and compute data asynchronously.

import asyncio
import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Base atoms
    page.state.atom("user_id", 1)

    # Async selector - fetches user data
    @page.state.selector("user_data")
    async def fetch_user(get):
        user_id = get("user_id")

        # Simulate API call
        await asyncio.sleep(1)

        # Mock user data
        users = {
            1: {"name": "Alice", "email": "[e-mail]"},
            2: {"name": "Bob", "email": "[e-mail]"},
            3: {"name": "Charlie", "email": "[e-mail]"}
        }

        return users.get(user_id, {"name": "Unknown", "email": "N/A"})

    # UI
    user_info = ft.Ref[ft.Text]()

    def update_user_info(user_data):
        # Async selectors may return coroutines on first call, check the type
        import inspect
        if inspect.iscoroutine(user_data):
            # Skip coroutine objects - they will be resolved automatically
            return
        if user_data:
            user_info.current.value = f"{user_data['name']} ({user_data['email']})"
        else:
            user_info.current.value = "Loading..."
        page.update()

    def next_user(e):
        current_id = page.state.get("user_id")
        page.state.set("user_id", (current_id % 3) + 1)

    # Listen to selector changes
    page.state.listen("user_data", update_user_info)

    page.add(
        ft.Column([
            ft.Text("User Profile", size=24),
            ft.Text(ref=user_info, size=18),
            ft.ElevatedButton("Next User", on_click=next_user)
        ])
    )

ft.app(target=main)

---

Shopping Cart Example

Real-world e-commerce state management.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # State
    page.state.atom("cart_items", [])

    # Selectors
    @page.state.selector("cart_total")
    def calculate_total(get):
        items = get("cart_items")
        return sum(item["price"] * item["quantity"] for item in items)

    @page.state.selector("cart_count")
    def count_items(get):
        items = get("cart_items")
        return sum(item["quantity"] for item in items)

    # Available products
    products = [
        {"id": 1, "name": "Laptop", "price": 999.99},
        {"id": 2, "name": "Mouse", "price": 29.99},
        {"id": 3, "name": "Keyboard", "price": 79.99}
    ]

    # UI refs
    cart_list = ft.Ref[ft.Column]()
    cart_count_text = ft.Ref[ft.Text]()
    cart_total_text = ft.Ref[ft.Text]()

    def add_to_cart(product):
        items = page.state.get("cart_items")

        # Check if item already in cart
        existing = next((item for item in items if item["id"] == product["id"]), None)

        if existing:
            existing["quantity"] += 1
        else:
            items.append({**product, "quantity": 1})

        page.state.set("cart_items", items)

    def render_cart():
        items = page.state.get("cart_items")

        cart_list.current.controls = [
            ft.ListTile(
                title=ft.Text(item["name"]),
                subtitle=ft.Text(f"${item['price']:.2f} × {item['quantity']}"),
                trailing=ft.Text(f"${item['price'] * item['quantity']:.2f}")
            ) for item in items
        ] if items else [ft.Text("Cart is empty")]

        page.update()

    # Listen to cart changes
    page.state.listen("cart_items", lambda _: render_cart())

    # Build UI
    page.add(
        ft.Row([
            # Products column
            ft.Column([
                ft.Text("Products", size=24),
                *[
                    ft.ElevatedButton(
                        f"{p['name']} - ${p['price']:.2f}",
                        on_click=lambda e, product=p: add_to_cart(product)
                    ) for p in products
                ]
            ], expand=1),

            # Cart column
            ft.Column([
                ft.Text("Shopping Cart", size=24),
                ft.Text(ref=cart_count_text),
                ft.Column(ref=cart_list),
                ft.Divider(),
                ft.Text(ref=cart_total_text, size=20, weight=ft.FontWeight.BOLD)
            ], expand=1)
        ])
    )

    # Bind computed values
    page.state.bind("cart_count", cart_count_text, prop="value")
    page.state.bind("cart_total", cart_total_text, prop="value")

    render_cart()

ft.app(target=main)

---

⚡ Performance & Python 3.14+

Flet-ASP includes a hybrid update strategy that ensures bindings work reliably, even when controls are bound before being added to the page.

Hybrid Strategy:

1. Lazy updates - Property is always set (never fails)
2. Immediate updates - Tries to update if control is mounted (99% of cases)
3. Lifecycle hooks - Hooks into did_mount for custom controls
4. Queue fallback - Retries when page.update() is called

Python 3.14+ Optimizations:

Feature	Benefit	Performance Gain
Free-threading	Process bindings in parallel without GIL	Up to 4x faster for large apps
Incremental GC	Smaller garbage collection pauses	10x smaller pauses (20ms → 2ms)
Tail call interpreter	Faster Python execution	3-5% overall speedup

Configuration (optional):

from flet_asp.atom import Atom

# For giant apps with 1000+ bindings on Python 3.14+
Atom.MAX_PARALLEL_BINDS = 8

# For small apps or to disable free-threading
Atom.ENABLE_FREE_THREADING = False

For more details, see PERFORMANCE.md.

---

📁 More Examples

Explore the examples/ folder for complete applications:

Basic Examples:

• 1.0_counter_atom.py - Simple counter
• 1.1_counter_atom_using_state_alias.py - Counter with page.state
• 2_counter_atom_bind_dynamic.py - Dynamic binding

Intermediate Examples:

• 3_computed_fullname.py - Computed state
• 4_action_login.py - Async actions
• 5_selector_user_email.py - Selectors
• 6_listen_user_login.py - State listeners
• 7_bind_two_way_textfield.py - Two-way binding
• 8_session_reset_clear.py - State cleanup

Advanced Examples:

• 9_todo.py - Complete ToDo app
• 10_cart_app.py - Shopping cart
• 11_screen_a_navigation_screen_b.py - Navigation with page.state
• 11.1_global_state_outside.py - Global state outside page scope
• 12_python314_performance.py - Performance demo
• 13_hybrid_binding_advanced.py - Hybrid binding

Atomic Design Examples:

• 14_atomic_design_dashboard/ - Complete dashboard with atoms, molecules, organisms, templates, and pages
• 15_atomic_design_theming/ - Theme-aware component library with design tokens
• 16_reactive_atomic_components/ - Reactive components with built-in state management

---

🧩 Building Design Systems with Atomic Design

Flet-ASP is designed from the ground up to work seamlessly with the Atomic Design methodology - a powerful approach for building scalable, maintainable design systems.

What is Atomic Design?

Atomic Design is a methodology for creating design systems by breaking down interfaces into fundamental building blocks, inspired by chemistry:

🔬 Atoms → 🧪 Molecules → 🧬 Organisms → 📄 Templates → 📱 Pages

How Flet-ASP Maps to Atomic Design

Atomic Design Layer	Flet-ASP Feature	Example
Atoms	Reactive state values	page.state.atom("email", "")
Molecules	Computed state	@page.state.selector("full_name")
Organisms	Actions & workflows	Action(login_function)
Templates	State bindings	page.state.bind("count", ref)
Pages	Complete screens	Custom controls with encapsulated state

Real-World Atomic Design with Flet-ASP

We provide two comprehensive examples that demonstrate professional design system architecture:

📊 Example 14: Dashboard Design System

A complete dashboard application showcasing the full Atomic Design hierarchy:

• Atoms: Buttons, inputs, text styles, icons, dividers
• Molecules: Stat cards, menu items, form fields, search bars
• Organisms: Sidebar, top bar, data tables, stats grid
• Templates: Dashboard layouts with different content arrangements
• Pages: Dashboard, analytics, users, orders, settings screens

# Atoms define the foundation
from atoms import heading1, primary_button

# Molecules combine atoms
from molecules import stat_card

# Organisms compose molecules
from organisms import stats_grid

# Templates arrange organisms
from templates import dashboard_template

# Pages bring it all together
from pages import dashboard_page

Features:

• ✅ Complete component hierarchy following Atomic Design
• ✅ Real-time data updates with reactive state bindings
• ✅ Navigation with state preservation
• ✅ Reusable components across multiple pages
• ✅ Consistent design language

View Example →

🎨 Example 15: Theme-Aware Component Library

An advanced example demonstrating design tokens and dynamic theming:

• Design Tokens: Colors, typography, spacing, border radius
• Theme-Aware Atoms: Components that adapt to light/dark modes
• Reactive Theming: Real-time theme switching with flet-asp
• Semantic Colors: Success, warning, error, info states

from theme_tokens import get_theme
from atoms import filled_button, text_field
from molecules import alert, stat_card

# All components automatically adapt to current theme
theme = get_theme()
button = filled_button("Submit")  # Uses theme.colors.primary

Features:

• ✅ Complete design token system (colors, typography, spacing)
• ✅ Light and dark mode support
• ✅ Theme switching without page reload
• ✅ Semantic color system for alerts and states
• ✅ Professional design system architecture

View Example →

⚛️ Example 16: Reactive Atomic Components

Components that combine visual structure + reactive state in a single, reusable package:

from reactive_atoms import ReactiveCounter, ReactiveStatCard, ReactiveForm

# Create counter with built-in state!
counter = ReactiveCounter(page, "Counter A", initial_count=0)
page.add(counter.control)

# Interact via clean API
counter.increment()  # +1
counter.decrement()  # -1
counter.reset()      # Set to 0
print(counter.value) # Get current value

# Stat card with auto-updates
users_card = ReactiveStatCard(
    page,
    title="Total Users",
    atom_key="users",
    initial_value="1,234",
    icon_name=ft.Icons.PEOPLE,
    show_trend=True
)

# Update programmatically
users_card.update_with_trend("2,500", "+15%")  # ✨ UI updates automatically!

Features:

• ✅ Components with built-in reactive state
• ✅ No manual binding needed
• ✅ Clean, intuitive API
• ✅ Encapsulated state management
• ✅ Reusable across projects

View Example →

Why Atomic Design + Flet-ASP?

🎯 Consistency: Design tokens and atoms ensure uniform styling across your app

🔄 Reusability: Build components once, use them everywhere with different state bindings

📈 Scalability: Add new features by combining existing atoms and molecules

🧪 Testability: Test atoms, molecules, and organisms in isolation

🤝 Collaboration: Designers and developers work with the same component language

⚡ Reactivity: State changes propagate automatically through the component hierarchy

Learn More About Atomic Design

• Atomic Design by Brad Frost - The definitive guide
• Building Design Systems with Atomic Design
• Material Design System - Real-world example
• Flet-ASP Examples - Practical implementations

---

🌐 Community

Join the community to contribute or get help:

• Discord
• GitHub Issues

⭐ Support

If you like this project, please give it a GitHub star ⭐

---

🤝 Contributing

Contributions and feedback are welcome!

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with detailed explanation

For feedback, open an issue with your suggestions.

---

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