Added Commands Management

README.md

@@ -1,3 +1,179 @@
-# MyFastHtml Module
+# MyFastHtml
 
-Set of tools to quickly create HTML pages using FastHTML.
+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.)
+```