96 lines
6.2 KiB
Markdown
96 lines
6.2 KiB
Markdown
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).
|