Improved docs

versioned_docs/version-0.2.0/00-intro/02-getting-started.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+title: Getting Started
+---
+
+# Getting Started: Hello World
+
+Let's write a minimal OSUI application that displays "Hello World" in the terminal. This example will introduce you to the core concepts of an OSUI application: the `Console` engine, running an application, and defining a basic component with `rsx!`.
+
+## 1. Create a New Project
+
+If you haven't already, create a new Rust binary project:
+
+```bash
+cargo new hello-osui
+cd hello-osui
+```
+
+## 2. Add OSUI Dependency
+
+```bash
+cargo add osui
+```
+
+## 3. Write the Hello World Code
+
+Open `src/main.rs` and replace its contents with the following:
+
+```rust title="src/main.rs"
+use osui::prelude::*; // Import commonly used OSUI items
+use std::sync::Arc;
+
+pub fn main() {
+    // 1. Initialize the Console engine
+    // The Console engine uses crossterm to interact with the terminal.
+    let engine = Console::new();
+
+    // 2. Run the application
+    // The `run` method takes your root component and starts the rendering loop.
+    // It returns a `Result`, which we unwrap here for simplicity.
+    engine.run(App {}).expect("Failed to run OSUI application");
+}
+
+/// 3. Define your root component
+/// The `#[component]` attribute transforms a function into a reusable UI component.
+/// - The first parameter `cx: &Arc<Context>` is mandatory and provides access to component context (state, events, children).
+/// - Components must return a `View`.
+#[component]
+fn App(cx: &Arc<Context>) -> View {
+    // 4. Use RSX (React-like Syntax) to define the UI
+    // `rsx!` is a procedural macro for declarative UI construction.
+    // Here, it just renders a simple string literal.
+    rsx! {
+        "Hello World"
+    }
+    // `view(&cx)` converts the RSX into a `View` that can be rendered.
+    .view(&cx)
+}
+```
+
+## 4. Run Your Application
+
+Execute your application from the terminal:
+
+```bash
+cargo run
+```
+
+You should see "Hello World" displayed in your terminal, which will then clear when the application exits.
+
+## Understanding the Code
+
+Let's break down the key parts of the "Hello World" example:
+
+*   **`use osui::prelude::*;`**: This line imports the `prelude` module, which re-exports the most commonly used types and macros from OSUI. This includes `Console`, `Context`, `View`, `#[component]`, and `rsx!`.
+*   **`Console::new()`**: The `Console` struct is OSUI's default rendering engine. It uses the `crossterm` library to draw content to your terminal.
+*   **`engine.run(App {})`**: This starts the OSUI application lifecycle. It takes an instance of your root component (`App {}` in this case) and begins the continuous rendering loop. The `App` component will be rendered repeatedly until the application is stopped (e.g., by pressing `Ctrl+C` or a command from within the app).
+*   **`#[component] fn App(cx: &Arc<Context>) -> View { ... }`**:
+    *   The `#[component]` attribute is a procedural macro that transforms a standard Rust function into an OSUI component. This enables prop handling and integration into the component tree.
+    *   All component functions must take `cx: &Arc<Context>` as their first argument. The `Context` provides access to component-specific state, lifecycle methods, event handlers, and the ability to add child components.
+    *   Component functions must return a `View`, which is an `Arc<dyn Fn(&mut DrawContext) + Send + Sync>`. This `View` represents the instructions for rendering the component.
+*   **`rsx! { "Hello World" }.view(&cx)`**:
+    *   The `rsx!` macro is OSUI's declarative UI syntax. It allows you to define a hierarchy of components and text nodes in a way that feels similar to HTML or React's JSX.
+    *   In this simple case, `"Hello World"` is a text literal that `rsx!` converts into a renderable element.
+    *   The `.view(&cx)` method takes the `Rsx` object generated by the `rsx!` macro and processes it within the current `Context`, ultimately producing the final `View` to be returned by the component.
+
+This simple example demonstrates the fundamental building blocks of an OSUI application. Next, we'll explore how to create more complex components and pass data between them.
+
+**Next:** Learn about [Creating Components](./03-example-basic-component.md) and passing them data.