Updated docs

Author: maximebf

docs/assets/stylesheets/home.css

@@ -5,8 +5,6 @@
 
 #home-hero {
     position: relative;
-    height: 650px;
-    max-height: 100vh;
     margin-top: -2.5rem;
 
     svg {
@@ -39,7 +37,7 @@
         color: #fff;
         text-align: center;
         max-width: 1000px;
-        margin: 4.5rem auto 0;
+        margin: 4.5rem auto 2rem;
         h1 {
             font-family: "Poppins", sans-serif;
             font-size: 2.5rem;
@@ -88,11 +86,10 @@
     padding: 2rem 0;
 
     > div {
-        display: grid;
-        grid-template-columns: 1fr 1fr 1fr;
         gap: 2rem;
         margin: 0 auto;
         max-width: 1220px;
+        padding: 0 .8rem;
 
         h2 {
             font-size: 1.5rem;
@@ -115,6 +112,14 @@
     }
 }
 
+@media (min-width: 768px) {
+    #home-intro > div {
+        display: grid;
+        grid-template-columns: 1fr 1fr 1fr;
+        padding: 0;
+    }
+}
+
 #home-technos {
     display: flex;
     flex-wrap: wrap;
@@ -132,8 +137,6 @@
 }
 
 .home-feature {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
     gap: 2rem;
 
     h2 {
@@ -149,14 +152,30 @@
     img {
         display: block;
         margin: 0 auto;
-        max-width: 600px;
         max-height: 300px;
+        max-width: 100%;
     }
 }
 .home-feature + .home-feature {
     margin-top: 4rem;
 }
 
+@media (min-width: 768px) {
+    .home-feature {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+
+        img {
+            max-width: 600px;
+        }
+    }
+    .home-feature:nth-child(odd) {
+        > div:first-child {
+            order: 2;
+        }
+    }
+}
+
 .md-tabs {
     margin-top: 2.5rem;
     color: #fff;

docs/components/layout.md

@@ -0,0 +1,30 @@
+# Layout
+
+Hyperflask includes a few utilties to help you design your app quickly.
+
+## Common app UI
+
+Use the following snippet to kick start a very common application UI with a sidebar:
+
+```
+<{AppUI}>
+    <{Viewport}>
+
+    </{Viewport}>
+    <{Sidebar}>
+
+    </{Sidebar}>
+</{AppUI}>
+```
+
+Use the [Menu](/components/daisyui/Menu) component to create menus in the sidebar.
+
+Viewport is a vertical flexbox with overflow by default. Use `<{Viewport overflow=False}>` for no overflowing.
+
+## Flex boxes
+
+Use `<{HBox}>` and `<{VBox}>` for respectively row and column flexbox with a gap between each items.
+
+Use `<{CenterBox}>` for a box which content is vertically and horizontally centered.
+
+Use `<{Spacer}/>` to add a growing div that takes all the space between 2 items.

docs/getting-started.md

@@ -224,7 +224,7 @@ def post():
         current_app.sse.publish("messages", current_app.components.ChatMessage(message=msg), private=True)
 ---
 {% form %}
-<{HxForm form action=url_for("PostMessageForm") hx_swap="outerHTML"}>
+<{HxForm form action=url_for("PostMessageForm") hx_swap="none"}>
     <{FormField form.message.textarea(required=True, placeholder="Chat") }/>
     <{SubmitButton}>Send</{}>
 </{HxForm}>
@@ -239,7 +239,7 @@ from app.models import Message
 page.messages = Message.find_all()
 ---
 {% use_layout %}
-<{MercureStream topic="messages" id="messages"}>
+<{MercureStream topic="messages"}>
     {% for msg in messages %}
         <{ChatMessage message=msg }/>
     {% endfor %}
@@ -285,6 +285,8 @@ Modify the component `ChatMessage` to display the author:
 
 Finally, add `page.login_required()` at the top of your page frontmatter to require authentication to access it.
 
+Upon accessing your site, you will be asked to connect using an email address. No confirmation will be asked on first connection. On further connections, you will be asked for a code to complete the connection. Go to <http://localhost:8025> to access [Mailpit](https://github.com/axllent/mailpit) and read the emails.
+
 ## Deploying to production
 
 Signup for an account on Fly.io or any VPS provider (eg: Digital Ocean) then run the following command from a VS Code terminal (while connected to the dev container):

docs/guides/components.md

@@ -86,114 +86,6 @@ Example using the previous *app/components/Dropdown.html*:
 </div>
 ```
 
-## Backend logic and interactions with HTMX
-
-Components can define their own custom backend logic. Similar to pages, files should use the *jpy* extension and provide a frontmatter with the python code.
-
-Functions named after HTTP methods will be registered as routes. For example, if a *get* function exists, Hyperflask will make the component accessible through GET requests.  
-These functions can return a dict with component props to render the component or any other valid Flask response value.
-
-Use HTMX to call your component logic and retrieve only the necessery HTML.
-
-Let's create a todo app:
-
-*app/pages/index.jpy*:
-
-```
----
-from app.models import Todo
-page.todos = Todo.find_all()
----
-<table>
-    {% for todo in todos %}
-        <{TodoItem todo=todo }/>
-    {% endfor %}
-</table>
-<button hx-get="{{url_for('TodoItemForm')}}" hx-target="previous" hx-swap="beforeend">Add todo</button>
-```
-
-*app/components/TodoItem.jpy*:
-
-```
----
-from app.models import db, Todo
-
-def get():
-    todo = Todo.get_or_404(request.args['id'])
-    return {"todo": todo}
-
-def delete():
-    with db:
-        todo = Todo.get_or_404(request.args['id'])
-        todo.delete()
-    return ""
----
-<tr>
-    <td>{{props.todo.title}}</td>
-    <td>
-        <button hx-get="{{url_for('TodoItemForm', id=props.todo.id)}}" hx-target="closest tr" hx-swap="outerHTML">Delete</button>
-        <button hx-delete="{{url_for('TodoItem', id=props.todo.id)}}" hx-target="closest tr" hx-swap="delete">Delete</button>
-    </td>
-</tr>
-```
-
-*app/components/TodoItemForm.jpy*:
-
-```
----
-from hyperflask import request, current_app
-from app.models import db, Todo
-
-def get():
-    todo = Todo.get_or_404(request.args['id']) if "id" in request.args else None
-    return {"todo": todo}
-
-def post():
-    with db:
-        if "id" in request.values:
-            todo = Todo.get_or_404(request.args['id'])
-        else:
-            todo = Todo()
-        todo.title = request.form["title"]
-        todo.save()
-    return current_app.components.TodoItem(todo=todo) # return another component
----
-<tr>
-    <td>
-        <input type="text" name="title" value="{{props.todo.title if props.todo else ''}}" required>
-    </td>
-    <td>
-        <button hx-get="{{url_for('TodoItemForm', id=props.todo.id if props.todo else None)}}" hx-include="closest tr" hx-target="closest tr" hx-swap="outerHTML">Save</button>
-    </td>
-</tr>
-```
-
-!!! warning
-    Unlike pages, all python imports are mandatory in components
-
-!!! tip
-    The `request` object in Hyperflask uses [htmx-Flask](https://github.com/sponsfreixes/htmx-flask) subclass that [provides easy access to htmx headers](https://github.com/sponsfreixes/htmx-flask?tab=readme-ov-file#usage).
-
-### HTMX utilities
-
-Perform an htmx redirection using `htmx_redirect()`:
-
-```py
-from hyperflask import htmx_redirect
-def post():
-    # ...
-    return htmx_redirect("/")
-```
-
-Perform an Out-Of-Band (oob) swap using `htmx_oob()`:
-
-```py
-from hyperflask import htmx_oob
-def post():
-    # ...
-    return htmx_oob(current_app.components.Sidebar()) # replaces the sidebar element with a new version of itself
-```
-
 ## Styling and scripting
 
 Scripts and styles can be embedded in components and bundled automatically.
@@ -231,7 +123,7 @@ In a template: `<{custom_dropdown}/>`
 
 ### React components
 
-Define react components as usual in a jsx file named after the component. Call them in your template like any other component. Each component call will create an independant react tree.
+Define react components as usual in a jsx file named after the component. You must export your component as default. Call them in your template like any other component. Each component call will create an independant react tree.
 
 !!! important
     React is not bundled with Hyperflask. You will need to install it using npm.
@@ -241,7 +133,7 @@ Properties provided to the component will be serialized to JSON. You cannot prov
 Example, *app/components/Dropdown.jsx*:
 
 ```js
-function Dropdown(props) {
+export default function Dropdown(props) {
     return <div></div>;
 }
 ```
@@ -252,4 +144,21 @@ In a template: `<{Dropdown}/>`
 
 Hyperflask includes a rich library of UI components powered by [DaisyUI](https://daisyui.com).
 
-Check out the [Components library](/components)
+Check out the [Components library](/components)
+
+## Components with custom logic
+
+For backend components, you can execute business logic before rendering the template.
+Use a jinjapy file instead of html file (.jpy extension) and implement the render function.
+
+The render function will be provided the props as arguments.
+
+```
+---
+def render(prop1, prop2):
+    # custom logic
+    return {"var": "value"} # template variables
+---
+{{var}}
+---
+```

docs/guides/config.md

@@ -26,6 +26,21 @@ An environment specific *.env* file can also be created following the format *.e
 
 ## Common configuration values
 
-| Key | Description | Default location | Default value |
+See [Flask documentation](https://flask.palletsprojects.com/en/stable/config/#builtin-configuration-values) for the full list of Flask options.
+
+Each Flask extension may have their own configuration.
+
+| Key | Type | Description | Default value |
 | --- | --- | --- | --- |
-| SECRET_KEY | The encryption key for all secret values (including the session) | .env | random
+| SECRET_KEY | str | The encryption key for all secret values (including the session) (set by default in .env) | random
+| SITE_TITLE | str |  |
+| SITE_LANG | str |  |
+| ASSETS_INCLUDE_HTMX | bool |  |
+| HTMX_EXT | list[str] |  |
+| HTMX_BOOST_SITE | bool |  |
+| EMAIL_BACKGROUND_COLOR | str |  |
+| EMAIL_BACKGROUND_ACCENT_COLOR | str |  |
+| STATIC_MODE | str |  |
+| MARKDOWN_OPTIONS | dict |  |
+| FLASH_TOAST_OOB | bool | Whether to add flash messages to htmx request as oob swaps |
+| FLASH_TOAST_REMOVE_AFTER | str | Use the remove-me htmx extension to auto remove the toast alerts after some time |

docs/guides/deploy.md

@@ -3,8 +3,14 @@
 !!! info
     This feature is provided by [Docker Web Deploy](https://github.com/hyperflask/docker-web-deploy)
 
+## Build & deploy
+
 Run the following command:
 
 ```
-$ hyperflask deploy
-```
+$ uv run hyperflask deploy
+```
+
+## Build only
+
+When using Hyperflask-Start, the app is containerized. Run `docker build .` to build the image.

docs/guides/flash.md

@@ -0,0 +1,7 @@
+# Flash messages
+
+Flask [provides a mechanism](https://flask.palletsprojects.com/en/stable/patterns/flashing/) for showing one time messages to the user.
+
+Use `flash()` or `page.flash()` as described by Flask documentation.
+
+Hyperflask will automatically print the messages as [alert messages in a toast](https://daisyui.com/components/toast/). This will also work when flashing messages during ajax requests.