Convert README.md to mkdocs-built documentation

Author: imankulov

README.md

@@ -0,0 +1,16 @@
+# Component IDs
+
+- Every component must have a root element that includes its ID. The ID is `id={{ component_id }}`.
+- Component IDs represent the component hierarchy and are formatted as "|parent:id|child:id". For example, we can have a component |form:0|button:submit where "button" is the component type, "submit" is its name, and "form:0" is its parent.
+
+In many contexts, you get access to the StateAddress object, which consists of the session ID and the component ID.
+In this pair, the component ID is a "ComponentId" instance (a subclass of str), which has a helpful method
+to create child items.
+
+It can be used like this, without explicitly setting the child own_id:
+
+    state_address.component_id | "child_component"
+
+Or like this, with explicitly setting the child own_id:
+
+    state_address.component_id | ("child_component", "child_own_id")

docs/component_ids.md

@@ -0,0 +1,160 @@
+# Components
+
+## Component State
+
+The state is defined in a separate class. The state must include parameters, passed to the component as keyword arguments, so that the component gets all necessary information to re-render itself on partial render.
+
+For example, given the template the alert component:
+
+```html
+<alert>{{ message }}</alert>
+```
+
+that you want to use as
+
+```html
+{% component "alert" message="Hello, world!" %}
+```
+
+Assuming that the component will be re-rendered on partial render, the state must include the "message" parameter:
+
+```python
+from pydantic import BaseModel
+from livecomponents.component import LiveComponent
+from livecomponents.manager.manager import InitStateContext
+
+class AlertState(BaseModel):
+    message: str = ""
+
+
+class Alert(LiveComponent):
+
+    template_name = "alert.html"
+
+
+    def init_state(self, context: InitStateContext) -> AlertState:
+        return AlertState(**context.component_kwargs)
+```
+
+Component states don't need to be stored if components are not expected to be re-rendered independently, and only
+as part of the parent component. For example, components for buttons are rarely re-rendered independently, so
+you get away without the state model.
+
+## Serializing Component State
+
+When the page is rendered for the first time, a new session is created, and each component is initialized with its
+state by calling the `init_state()` method.
+
+The state is then serialized and stored in the session store, and as long as the session is the same (in other words,
+while the page is not loaded), the state is reused.
+
+The state is serialized using the `StateSerializer` class and saved in Redis. By default, the `PickleStateSerializer`
+is used. The serializer uses custom pickler and is optimized to store effectively the most common types of data, used
+in a Django app. More specifically:
+
+- When serializing a Django model, only the model's name and primary key are stored. The serializer takes advantage of
+  the persistent_id/persistent_load pickle mechanism.
+- When serializing a Pydantic model, only the model's name and the values of the fields are stored.
+- When serializing a Django form, only the form's class name, as well as initial data and data, are stored.
+
+
+## Stateless components
+
+If the component doesn't store any state, you can inherit it from the StatelessLiveComponent class. You may find it
+helpful for rendering the hierarchy of components where the shared state is stored in the root components.
+
+```python
+from livecomponents.component import StatelessLiveComponent
+
+class StatelessAlert(StatelessLiveComponent):
+
+    template_name = "alert.html"
+
+    def get_extra_context_data(
+        self, extra_context_request: "ExtraContextRequest[State]"
+    ) -> dict:
+        state_manager = extra_context_request.state_manager
+        root_addr = extra_context_request.state_addr.must_find_ancestor("root")
+        root_state = state_manager.get_component_state(root_addr)
+        return {"message": root_state.message}
+```
+
+## Returning results from command handlers
+
+Here's the signature of the Livecomponent function:
+
+```python
+from livecomponents import LiveComponent, CallContext, command
+from livecomponents.manager.execution_results import IExecutionResult
+
+class MyComponent(LiveComponent):
+
+    @command
+    def my_command_handler(self , call_context: CallContext, **kwargs) -> list[IExecutionResult] | IExecutionResult | None :
+        ...
+```
+
+Notice the type of the returned value for the handler. If set to something other than None, it can shape the
+partial HTTP response.
+
+More specifically here's what you can do:
+
+- Return ComponentDirty() to mark the component as dirty. This will result in the component being re-rendered and sent to the client. This is the default behavior. If you don't return anything, the component will be marked as dirty.
+- Return ComponentDirty(component_id) to mark a different component as dirty.
+- Return ComponentClean() to mark the current component as clean (not needing re-rendering).
+- Return ParentDirty() to mark the parent component as dirty.
+- Return RefreshPage(). If the command returns RefreshPage(), a "HX-Refresh: true" header will be sent to the client.
+- Return RedirectPage(url). If the command returns Redirect(), a "HX-Redirect: url" header will be sent to the client.
+- Return ReplaceUrl(url). If the command returns ReplaceUrl(), a "HX-Replace: url" header will be sent to the client. This will replace the current URL in the browser without reloading the page.
+
+## Raising exceptions from command handlers
+
+In some rare scenarios, you may need to cancel rendering the component and instruct the command handler to return an empty string to the client.
+
+If this is the case, you can raise a `livecomponents.exceptions.CancelRendering()` exception.
+
+The exception can be raised directly from a command handler or from one of the methods that it will call, such as `get_extra_context_data()`.
+
+```python
+from livecomponents.exceptions import CancelRendering
+...
+
+class MyComponent(LiveComponent):
+
+    @command
+    def my_command_handler(self, call_context: CallContext, **kwargs):
+        if not self.pre_condition_met(call_context):
+            raise CancelRendering()
+        ...
+```
+
+We encountered this situation at least once, where a race condition caused the pre-condition that was true when we started executing a command to no longer be true when we rendered a sub-component. In this case, we couldn't render the sub-component but also didn't want to return a partially rendered component. The best solution was to return an empty string, effectively making the command have no effect.
+
+
+## Calling component methods from others
+
+There are several ways to call component methods from other components:
+
+**Using the component ID.** For example, if you have a component with ID "|message.0" and a method "set_message", you can call it like this:
+
+```python
+from livecomponents import LiveComponent, command, CallContext
+
+class MyComponent(LiveComponent):
+
+    @command
+    def do_something(self, call_context: CallContext):
+        call_context.find_one("|message:0").set_message("Hello, world!")
+```
+
+**Using the "parent" reference.**
+
+```python
+from livecomponents import LiveComponent, command, CallContext
+
+class MyComponent(LiveComponent):
+
+    @command
+    def do_something(self, call_context: CallContext):
+        call_context.parent.set_message("Hello, world!")
+```

docs/components.md

@@ -0,0 +1,22 @@
+# Configuration
+
+The application is configured with the "LIVECOMPONENTS" dictionary in the settings.py file. Here's the default settings:
+
+```python
+LIVECOMPONENTS = {
+    "state_serializer": {
+        "cls": "livecomponents.manager.serializers.PickleStateSerializer",
+        "config": {},
+    },
+    "state_store": {
+        # You can also use "MemoryStateStore" for tests.
+        "cls": "livecomponents.manager.stores.RedisStateStore",
+        # See "RedisStateStore" constructor for config options.
+        "config": {},
+    },
+    "state_manager": {
+        "cls": "livecomponents.manager.manager.StateManager",
+        "config": {},
+    },
+}
+```

docs/configuration.md

@@ -0,0 +1,28 @@
+# Storing Component Context
+
+During the first render, components use the entire page context to render themselves.
+
+During subsequent renders, components by default use the context populated from their state.
+
+However, it is possible to save some variables from the context of the first render. To do this, pass the `save_context` variable with a comma-separated list of variables that need to be sent to the `livecomponent` templatetag.
+
+This approach is commonly used when working with live component slots.
+
+Let's first look at an example of a "non-prepared" component that will only work on the first render:
+
+```html
+{% livecomponent_block "alert" %}
+  {% fill "body" %}Sending a message to {{ user.email }}!{% endfill %}
+{% endlivecomponent_block %}
+```
+
+This will not work on partial renders because the component will be rendered without the "user" variable.
+
+To address this, add the "save_context" variable:
+
+```diff
+-{% livecomponent_block "alert" %}
++{% livecomponent_block "alert" save_context="user" %}
+   {% fill "body" %}Sending a message to {{ user.email }}!{% endfill %}
+ {% endlivecomponent_block %}
+```

docs/context.md

@@ -0,0 +1,22 @@
+# Decorators
+
+LiveComponents provide a method decorator to ensure the user is authenticated.
+
+
+```python
+from livecomponents import LiveComponent, InitStateContext, CallContext
+from livecomponents.decorators import livecomponents_login_required
+
+
+class Something(LiveComponent):
+
+    @classmethod
+    @livecomponents_login_required
+    def init_state(cls, context: InitStateContext):
+        ...
+
+    @classmethod
+    @livecomponents_login_required
+    def do_something(cls, call_context: CallContext[SomethingState], **kwargs):
+        ...
+```

docs/decorators.md

@@ -0,0 +1,25 @@
+# Error handling
+
+The response to calling the command can be an HTTP error. If the command handler fails to find a session, it will return
+an HTTP 410 Gone error.
+
+You can handle this error on the client side. For example, here a JavaScript code snippet to reload the page on the
+error 410.
+
+```javascript
+document.addEventListener("htmx:responseError", function (event) {
+	const statusCode = event.detail.xhr.status;
+	if (statusCode === 410) {
+		document.location.reload();
+	}
+});
+```
+
+If you use [hyperscript](https://hyperscript.org/), you can write the same code much shorter as a one-liner, attached
+directly to the component, or to the document:
+
+```html
+<body ... _="on htmx:responseError[detail.xhr.status == 410] window.location.reload()">
+...
+</body>
+```

docs/error_handling.md

@@ -0,0 +1,13 @@
+# Example project
+
+While the fully fledged documentation is not ready and the project is in flux, it's better to use the "example" project as the reference.
+
+Run it locally and play with it to get a better understanding of how the library works.
+
+```bash
+poetry install
+cd example
+cp env.example .env
+poetry run python manage.py migrate
+poetry run python manage.py runserver
+```

docs/example_project.md

@@ -0,0 +1,5 @@
+# Django Live Components
+
+Django Live Component is a library to create dynamic web applications that handle user interaction with the DOM on the server. It relies on Django, HTMX, and Alpine.js to provide a seamless experience for developers and users.
+
+To get started, follow the [quickstart guide](quickstart.md)