Updated to 0.2.0

versioned_docs/version-0.2.0/reference/frontend-api.md

@@ -0,0 +1,78 @@
+markdown
+---
+sidebar_position: 3
+title: Frontend API
+---
+
+# Frontend Module API Reference
+
+The `frontend` module is responsible for bridging the declarative `rsx!` macro syntax to the dynamic component rendering system. It defines how component hierarchies are constructed and managed before being translated into `View`s.
+
+## `ToRsx` Trait
+
+```rust
+pub trait ToRsx {
+    fn to_rsx(&self) -> Rsx;
+}
+```
+
+The `ToRsx` trait is implemented by any type that can be converted into an `Rsx` object. This is crucial for embedding various types (like strings, numbers, or other `Rsx` instances) directly into the `rsx!` macro output using the `@{expr}` syntax.
+
+**Implementations:**
+*   **`&Rsx`**: Converts a reference to an `Rsx` into an owned `Rsx` by cloning its internal structure.
+*   **`T: std::fmt::Display`**: Any type that implements `std::fmt::Display` (e.g., `String`, `&str`, `i32`, `f64`, etc.) automatically implements `ToRsx`. It converts the displayable value into a `Rsx` containing a static scope that draws the text.
+
+## `RsxScope` Enum
+
+```rust
+#[derive(Clone)]
+pub enum RsxScope {
+    Static(Arc<dyn Fn(&Arc<Scope>) + Send + Sync>),
+    Dynamic(
+        Arc<dyn Fn(&Arc<Scope>) + Send + Sync>,
+        Vec<Arc<dyn HookDependency>>,
+    ),
+    Child(Rsx),
+}
+```
+
+`RsxScope` represents the different kinds of renderable units that can be part of an `Rsx` hierarchy. These scopes dictate how and when their content is processed and updated.
+
+*   **`Static(Arc<dyn Fn(&Arc<Scope>) + Send + Sync>)`**:
+    *   Represents content that is processed only once. This is typically used for simple text literals or components that don't depend on reactive state within their `rsx!`.
+    *   The contained closure is executed once to set up children within a new `Scope`.
+*   **`Dynamic(Arc<dyn Fn(&Arc<Scope>) + Send + Sync>, Vec<Arc<dyn HookDependency>>)`**:
+    *   Represents content that needs to be re-evaluated and potentially re-rendered when certain `dependencies` change. This is used for `rsx!` blocks with `@if` and `@for` that declare dependencies (`%dep`).
+    *   The closure (`drawer`) is executed initially and then whenever any of the `HookDependency` instances in `dependencies` notify an update.
+*   **`Child(Rsx)`**:
+    *   Represents a nested `Rsx` structure. This is used when an `Rsx` object is embedded directly into another `rsx!` block (e.g., via `@{other_rsx}` or when passing `children` to a component).
+
+## `Rsx` Struct
+
+```rust
+#[derive(Clone)]
+pub struct Rsx(Vec<RsxScope>);
+```
+
+The `Rsx` struct is a collection of `RsxScope`s, representing a declarative UI tree fragment. It's the primary output of the `rsx!` macro.
+
+#### Methods:
+
+*   **`fn new() -> Self`**
+    *   Creates a new empty `Rsx` instance.
+*   **`fn static_scope<F: Fn(&Arc<Scope>) + Send + Sync + 'static>(&mut self, scope: F)`**
+    *   Adds a `Static` `RsxScope` to the collection. The `scope` closure will be executed once to build up the content within a dedicated `Scope`.
+*   **`fn dynamic_scope<F: Fn(&Arc<Scope>) + Send + Sync + 'static>(&mut self, drawer: F, dependencies: Vec<Arc<dyn HookDependency>>)`**
+    *   Adds a `Dynamic` `RsxScope` to the collection. The `drawer` closure will be executed initially and then on subsequent updates of the specified `dependencies`.
+*   **`fn child<R: ToRsx>(&mut self, child: R)`**
+    *   Adds a `Child` `RsxScope` to the collection, converting the input `R` (which must implement `ToRsx`) into a nested `Rsx`.
+*   **`fn generate_children(&self, context: &Arc<Context>)`**
+    *   Processes the internal `Vec<RsxScope>`, converting each scope into actual component `Context`s and `Scope`s within the provided parent `context`. This method recursively builds the component tree.
+*   **`fn view(&self, context: &Arc<Context>) -> View`**
+    *   The primary method used by components to turn their `rsx!` output into a renderable `View`.
+    *   It first calls `generate_children` to build the component tree within the given `context`.
+    *   It then returns a `View` closure that, when executed, will instruct the `context` to `draw_children`.
+
+The `frontend` module, through `Rsx` and `RsxScope`, provides the declarative interface and the necessary translation layer to OSUI's imperative rendering core.
+
+**Next:** Explore the [Render API](./render-api.md).