fluvel 1.0.0b1
A modern, reactive, and high-performance GUI framework for Python based on PySide6.
Requires Python: <3.14,>=3.11
Keywords: gui, pyside6, qt, reactive, framework, declarative, desktop-apps

# Fluvel

![Current Version](https://img.shields.io/badge/Version-1.0.0b1-green)
  ![PyPI - License](https://img.shields.io/badge/License-LGPLv3--or--later-green)
  ![Python Version](https://img.shields.io/badge/Python-3.11+-blue)
  ![Platform Desktop](https://img.shields.io/badge/Platform-Desktop%20UI-blue)
  ![Integrated CLI](https://img.shields.io/badge/CLI-Integrated-C084FC)
  ![Hot Reloading](https://img.shields.io/badge/Hot--Reloading-Instantaneous-C084FC)
  
**Fluvel** is a framework built on top of **PySide6**. It abstracts the complexity of Qt by replacing manual layout management with **declarative context handlers** and a **Tailwind-inspired styling processor**. Powered by the **PYRO reactive engine**, it enables **deterministic state-to-UI binding** and a **decoupled resource architecture** (i18n/theming), ensuring that large-scale Python applications remain performant and easy to refactor.

**For complete documentation, tutorials, and architectural details, please visit our [GitHub Repository](https://github.com/fluvel-project/fluvel)**.

## Key Features

* **Declarative UI Architecture**: Interface definition via the `Page` abstract class, utilizing a **context-handler-based** syntax. This approach abstracts boilerplate layout logic, focusing on component hierarchy and structural intent.

* **PYRO Reactive Engine**: A standalone, agnostic state engine (*Pyro Yields Reactive Objects*) featuring **automatic dependency tracking**. It supports reactive primitives and collections (lists/dicts), enabling fine-grained UI binding and deterministic state synchronization.

* **Utility-First Styling & QSSProcessor**: High-performance styling via an integrated **token-based** system. The `QSSProcessor` parses inline utility classes and external QSS, facilitating rapid component skinning without manual stylesheet overhead.
    * *Example*: `Button(style="primary fg[red] b[2px solid blue]")`

* **Structural i18n & Logic Decoupling**: Separation of concerns through `.fluml` **(Fluvel Markup Language)** and XML schemas. This architecture decouples static/dynamic content from the Python business logic, enabling independent translation workflows and resource management.

* **Stateful Routing System**: Centralized navigation management via the `Router` class, handling page lifecycle and transitions within a unified application state.

* **Integrated Dev-Tools CLI**: A dedicated command-line interface for automated project scaffolding, asset management, and deployment workflows.

* **Hot-Reloading Environment**: A development-time watcher that performs **runtime hot-patching** of pages. It allows for instantaneous UI and theme iterations without destroying the application process or losing current state.

## 🚀 Quick Start

### 1. Installation
To install this version, use the following command:

```bash
# Setup environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# Install Fluvel
pip install fluvel
```

### 2. Starting a Project
Create your first application with the integrated CLI:

```bash
fluvel startproject
fluvel run
```

## License
Fluvel is an open-source project, licensed under the [GNU LGPL-3.0 Licence](https://www.gnu.org/licenses/lgpl-3.0.html) (or any later version).