Updated to 0.2.0

2026-01-31 20:52:02 +01:00
parent a30c1ac52a
commit 0b7a72dc5d
56 changed files with 7365 additions and 0 deletions
@@ -0,0 +1,95 @@
+markdown
+---
+sidebar_position: 0
+title: Core Architecture
+---
+
+# Core Architecture
+
+OSUI is designed with a clear separation of concerns, drawing inspiration from modern GUI frameworks like React. This modular architecture aims for flexibility, testability, and scalability. Here's a high-level overview of how the different parts of OSUI interact to form a functional TUI application.
+
+```mermaid
+graph TD
+    A[Application Root (main.rs)] --> B(Engine::run(RootComponent))
+    B --> C(Engine)
+    C -- init --> D(Root Component Context)
+    D -- refresh --> E(Root Component View)
+    E -- generate_children --> F(Frontend::Rsx)
+    F -- create Scopes & Contexts --> D
+    D -- draw_children --> G(Render::DrawContext)
+    G -- execute DrawInstructions --> H(Engine::draw_context)
+    H -- actual terminal output --> I(crossterm)
+
+    subgraph State & Events
+        J[Component Context] -- manage state via hooks --> K(State<T>)
+        K -- notify dependents --> L(HookEffect)
+        L -- trigger callbacks --> J
+        J -- emit events --> M(Event Handlers)
+        M -- propagate to children --> J
+    end
+
+    subgraph User Interaction
+        N[Input Polling Thread] --> O(Engine::CommandExecutor)
+        O -- execute commands --> C
+        O -- emit events --> J
+    end
+
+    C -- continuous loop --> E
+    D --> J
+    J --> E
+```
+
+## Key Architectural Components
+
+### 1. **Component System (`osui::component`)**
+
+*   **`ComponentImpl`**: The fundamental trait defining a renderable UI unit. Any type implementing this can be an OSUI component.
+*   **`Context`**: Each active component instance has its own `Context`. This is the central hub for:
+    *   Holding the component's `View` (its rendered output).
+    *   Managing its local state using hooks (e.g., `use_state`).
+    *   Registering and emitting events (`on_event`, `emit_event`).
+    *   Managing its children components and their `Scope`s.
+    *   Accessing the `CommandExecutor` to interact with the engine.
+*   **`Scope`**: A `Context` can contain multiple child `Scope`s. A `Scope` is primarily a container that groups a set of child components (`Context`s) and their optional `ViewWrapper`s. `Rsx` fragments generate `Scope`s to manage their children.
+
+**Why it works this way**: This component-based approach promotes modularity and reusability. `Context` provides a stable identity and state for each component instance, enabling independent updates and event handling. The tree structure formed by `Context`s and `Scope`s mirrors the UI hierarchy.
+
+### 2. **State Management (`osui::state`)**
+
+*   **`State<T>`**: A reactive wrapper for any data `T`. When `State<T>` is updated, it automatically notifies all its registered "dependents".
+*   **`use_state`**: The primary hook to create and manage `State<T>` within a component.
+*   **`use_effect`**: A hook for performing side effects (e.g., logging, network requests) in response to `State<T>` changes or component mounting.
+*   **`HookDependency`**: A trait that `State<T>` and `Mount` implement, allowing them to be tracked by `use_effect` and dynamic `rsx!` blocks.
+
+**Why it works this way**: Inspired by React hooks, this system provides a predictable and efficient way to manage mutable state. By declaring explicit dependencies for effects and dynamic `rsx!` blocks, OSUI can minimize re-renders and computations, only updating parts of the UI that are truly affected by state changes.
+
+### 3. **Frontend / Declarative UI (`osui::frontend` & `osui-macros`)**
+
+*   **`rsx!` macro**: A procedural macro that allows you to write UI using a declarative, XML-like syntax directly in Rust.
+*   **`#[component]` macro**: A procedural macro that transforms a Rust function into an OSUI component, automatically handling prop parsing and `ComponentImpl` implementation.
+*   **`Rsx`**: An internal representation (produced by `rsx!`) of a UI fragment, consisting of a vector of `RsxScope`s.
+*   **`RsxScope`**: An enum defining different types of UI nodes (static text, components, dynamic conditional/loop blocks).
+
+**Why it works this way**: Declarative UI is generally easier to reason about than imperative drawing commands. The `rsx!` macro provides a high-level abstraction that maps directly to the component tree and state management, significantly improving developer experience. The macro-generated `Rsx` object then serves as a blueprint for `Context` to build its children.
+
+### 4. **Rendering Pipeline (`osui::render`)**
+
+*   **`View`**: The ultimate output of a component's rendering logic. It's a closure that, when called, populates a `DrawContext` with drawing instructions.
+*   **`DrawContext`**: A mutable accumulator for `DrawInstruction`s. Components add text, child views, or custom drawing commands to this context. It also tracks the available `Area` and `allocated` space.
+*   **`DrawInstruction`**: An enum representing atomic drawing operations (e.g., `Text`, `View`, `Child`).
+*   **Geometric Primitives**: `Point`, `Size`, `Area` define positions and dimensions.
+
+**Why it works this way**: This separation allows the rendering logic to be independent of the actual display medium. Components declare *what* to draw using high-level instructions, and the `Engine` then decides *how* to execute them on the specific backend (e.g., terminal).
+
+### 5. **Engine (`osui::engine`)**
+
+*   **`Engine` trait**: Defines the interface for running an OSUI application, including initialization, continuous rendering, and managing the render loop.
+*   **`Console`**: The default implementation of `Engine`, which uses `crossterm` to interact with the terminal.
+*   **`CommandExecutor` trait**: An interface for executing system-level commands (e.g., `Stop`).
+*   **`Benchmark`**: A wrapper `Engine` that measures and reports performance statistics.
+
+**Why it works this way**: The `Engine` trait makes OSUI extensible. You can swap out the `Console` engine for a different backend (e.g., a web renderer, a headless testing engine) without changing your core component logic. The `CommandExecutor` provides a standardized way for components to request actions from the environment.
+
+This interconnected architecture allows OSUI to offer a powerful, flexible, and developer-friendly experience for building sophisticated Terminal User Interfaces.
+
+**Next:** Delve deeper into [The Component Model](./01-the-component-model.md).