# 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

### FastHtml Application

To create a simple FastHtml application, you can use the `create_app` function:

```python
from fasthtml import serve
from fasthtml.components import *

from myfasthtml.myfastapp import create_app

app, rt = create_app(protect_routes=False)


@rt("/")
def get_homepage():
  return Div("Hello, FastHtml!")


if __name__ == "__main__":
  serve(port=5002)


```

### Button with a Command

```python
from fasthtml import serve

from myfasthtml.controls.helpers import mk_button
from myfasthtml.core.commands import Command
from myfasthtml.myfastapp import create_app


# 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
app, rt = create_app(protect_routes=False)


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


if __name__ == "__main__":
  serve(port=5002)
```

- 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.)

## Relase History

* 0.1.0 : First release
* 0.2.0 : Updated to myauth 0.2.0