# MyFastHtml

A utility library designed to simplify the development of FastHtml applications by providing:
- Predefined pages for common functionalities (e.g., authentication, user management).
- A command management system to facilitate client-server interactions.
- Helpers to create interactive controls more easily.
- A system for control state persistence.

---

## Features

- **Dynamic HTML with HTMX**: Simplify dynamic interaction using attributes like `hx-post` and custom routes like `/commands`.
- **Command management**: Write server-side logic in Python while abstracting the complexities of HTMX.
- **Control helpers**: Easily create reusable components like buttons.
- **Predefined Pages (Roadmap)**: Include common pages like login, user management, and customizable dashboards.

> _**Note:** Support for state persistence is currently under construction._

---

## Installation

Ensure you have Python >= 3.12 installed, then install the library with `pip`:

```bash
pip install myfasthtml
```

---

## Quick Start

Here’s a simple example of creating an **interactive button** linked to a command:

### Example: Button with a Command

```python
from fasthtml.fastapp import fast_app
from myfasthtml.core.commands import Command
from myfasthtml.controls.button import mk_button

# Define a simple command action
def say_hello():
    return "Hello, FastHtml!"

# Create the command
hello_command = Command("say_hello", "Responds with a greeting", say_hello)

# Create the app and define a route with a button
app, rt = fast_app(default_hdrs=False)

@rt("/")
def get_homepage():
    return mk_button("Click Me!", command=hello_command)
```

- When the button is clicked, the `say_hello` command will be executed, and the server will return the response.
- HTMX automatically handles the client-server interaction behind the scenes.

---

## Planned Features (Roadmap)

### Predefined Pages
The library will include predefined pages for:
- **Authentication**: Login, signup, password reset.
- **User Management**: User profile and administration pages.
- **Dashboard Templates**: Fully customizable dashboard components.
- **Error Pages**: Detailed and styled error messages (e.g., 404, 500).

### State Persistence
Controls will have their state automatically synchronized between the client and the server. This feature is currently under construction.

---

## Advanced Features

### Command Management System
Commands allow you to simplify frontend/backend interaction. Instead of writing HTMX attributes manually, you can define Python methods and handle them as commands.

#### Example
Here’s how `Command` simplifies dynamic interaction:

```python
from myfasthtml.core.commands import Command

# Define a command
def custom_action(data):
    return f"Received: {data}"

my_command = Command("custom", "Handles custom logic", custom_action)

# Get the HTMX parameters automatically
htmx_attrs = my_command.get_htmx_params()
print(htmx_attrs)

# Output:
# {
#   "hx-post": "/commands", 
#   "hx-vals": '{"c_id": "unique-command-id"}'
# }
```

Use the `get_htmx_params()` method to directly integrate commands into HTML components.

---

## Contributing

We welcome contributions! To get started:
1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with clear descriptions of your changes.

For detailed guidelines, see the [Contributing Section](./CONTRIBUTING.md) (coming soon).

---

## License

This project is licensed under the terms of the MIT License. See the `LICENSE` file for details.

---

## Technical Overview

### Project Structure

```
MyFastHtml
├── src
│   ├── myfasthtml/             # Main library code
│   │   ├── core/commands.py    # Command definitions
│   │   ├── controls/button.py  # Control helpers
│   │   └── pages/LoginPage.py  # Predefined Login page
│   └── ...
├── tests                       # Unit and integration tests
├── LICENSE                     # License file (MIT)
├── README.md                   # Project documentation
└── pyproject.toml              # Build configuration
```

### Notable Classes and Methods

#### 1. `Command`
Represents a backend action with server communication.
- **Attributes:**
  - `id`: Unique identifier for the command.
  - `name`: Command name (e.g., `say_hello`).
  - `description`: Description of the command.
- **Method:** `get_htmx_params()` generates HTMX attributes.

#### 2. `mk_button`
Simplifies the creation of interactive buttons linked to commands.
- **Arguments:**
  - `element` (str): The label for the button.
  - `command` (Command): Command associated with the button.
  - `kwargs`: Additional button attributes.

#### 3. `LoginPage`
Predefined login page that provides a UI template ready for integration.
- **Constructor Parameters:**
  - `settings_manager`: Configuration/settings object.
  - `error_message`: Optional error message to display.
  - `success_message`: Optional success message to display.

---

## Entry Points

- `/commands`: Handles HTMX requests from the command attributes.

---

## Exceptions

No custom exceptions defined yet. (Placeholder for future use.)
```