Version 0.1.1

2025-08-10 14:14:04 -05:00
parent 54b9cba486
commit b4891d4795
39 changed files with 4587 additions and 0 deletions
@@ -0,0 +1,85 @@
+---
+slug: /
+---
+
+# Getting Started with OSUI
+
+This guide will walk you through setting up your Rust project to use OSUI and creating your first interactive terminal application.
+
+## 1. Project Setup
+
+First, create a new Rust project (if you haven't already):
+
+```bash
+cargo new my-osui-app
+cd my-osui-app
+```
+
+## 2. Add OSUI to Your `Cargo.toml`
+
+Open your `Cargo.toml` file and add `osui` to your `[dependencies]` section. You can also specify a particular version or use `*` for the latest compatible version.
+
+```toml
+# Cargo.toml
+[package]
+name = "my-osui-app"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+osui = "0.1.1" # Use the latest version available on crates.io
+crossterm = "0.28.1" # OSUI internally uses crossterm for terminal interactions
+figlet-rs = "0.1.5" # Optional: for Heading element (if you need it)
+```
+
+The `crossterm` and `figlet-rs` dependencies are automatically included by OSUI, but explicitly listing them doesn't hurt. OSUI uses `crossterm` for low-level terminal control and `figlet-rs` for the `Heading` element, which can render ASCII art text.
+
+## 3. Basic OSUI Application
+
+Now, let's create a minimal OSUI application. Open `src/main.rs` and replace its contents with the following:
+
+```rust
+use osui::prelude::*; // Import all necessary OSUI items
+
+fn main() -> std::io::Result<()> {
+    // Initialize the main screen abstraction.
+    // The Screen manages all widgets and extensions.
+    let screen = Screen::new();
+
+    // Register essential extensions:
+    // InputExtension: Handles keyboard input and dispatches events.
+    screen.extension(InputExtension);
+    // RelativeFocusExtension: Manages focus between widgets based on relative position,
+    // enabling navigation with arrow keys (e.g., in Flex layouts).
+    screen.extension(RelativeFocusExtension::new());
+
+    // Define your UI declaratively using the rsx! macro.
+    // This example creates a simple text string.
+    rsx! {
+        "Hello, OSUI!"
+    }
+    // Draw the defined UI tree onto the screen.
+    .draw(&screen);
+
+    // Start the main event loop. This blocks until the application is closed.
+    // It handles rendering, event processing, and extension updates.
+    screen.run()
+}
+```
+
+## 4. Run Your Application
+
+Save the file and run your application from the terminal:
+
+```bash
+cargo run
+```
+
+You should see "Hello, OSUI!" displayed in your terminal. You can press `Ctrl+C` or `Esc` (if you add an event handler for `Esc` like in the [Demo Application Guide](../guides/building-a-demo-app.md)) to exit the application.
+
+## Next Steps
+
+*   **[Concepts: Widget Model](../concepts/widget-model.md)**: Understand the core building blocks of OSUI: Elements, Components, and Widgets.
+*   **[Guides: Layout and Styling](../guides/layout-and-styling.md)**: Learn how to position and style your UI elements.
+*   **[Guides: Common Elements](../guides/common-elements.md)**: Explore the built-in UI elements provided by OSUI like Divs, Flex containers, and Input fields.
+*   **[Guides: State and Reactivity](../guides/state-and-reactivity.md)**: Discover how to make your UI dynamic and responsive to data changes.
@@ -0,0 +1,42 @@
+# OSUI: A Rust Terminal User Interface Library
+
+OSUI is a powerful and flexible library for building interactive and customizable terminal user interfaces (TUIs) in Rust. It provides a declarative component system, real-time keyboard input handling, and a JSX-like `rsx!` macro for defining UI elements, making TUI development intuitive and efficient.
+
+## Key Features
+
+*   **Declarative UI with `rsx!`**: Define your user interfaces using a familiar, expressive syntax similar to JSX, enhancing readability and maintainability.
+*   **Component-Based Design**: Build complex UIs from reusable, self-contained widgets and components, promoting modularity and reusability.
+*   **Reactive State Management**: Integrate dynamic behavior into your widgets with a built-in state management system that automatically triggers UI updates when data changes.
+*   **Flexible Layout and Styling**: Control widget positioning, dimensions, padding, margins, and visual appearance with a comprehensive styling API.
+*   **Extensible Architecture**: Customize and extend OSUI's core functionality through a robust extension system, allowing you to add custom behaviors, event handlers, and rendering logic.
+*   **Real-time Interaction**: Seamlessly handle keyboard inputs to create responsive and interactive command-line applications.
+*   **Virtual Screen Abstraction**: OSUI manages the underlying terminal drawing, providing a high-level abstraction for rendering your UI elements efficiently.
+
+## Quick Example
+
+Get started quickly with a simple "Hello, World!" example:
+
+```rust
+use osui::prelude::*;
+
+fn main() -> std::io::Result<()> {
+    // 1. Create a new Screen instance, which manages the TUI.
+    let screen = Screen::new();
+
+    // 2. Define your UI using the rsx! macro.
+    //    "👋 Hello, World!" is a simple text element.
+    rsx! {
+        "👋 Hello, World!"
+    }
+    // 3. Draw the defined UI onto the screen.
+    .draw(&screen);
+
+    // 4. Run the main rendering loop. This will keep the TUI active
+    //    and handle rendering and events until the application exits.
+    screen.run()
+}
+```
+
+This example initializes a `Screen`, uses the `rsx!` macro to define a basic text element, draws it to the screen, and then starts the rendering loop.
+
+For more detailed information on installation and setting up your project, refer to the [Getting Started Guide](../intro/getting-started.md). For comprehensive API details, explore the [Reference section](../reference/index.md).