docs: Add Theme, RootView doc. (#1408)

docs/docs/getting-started.md

@@ -6,22 +6,6 @@ order: -2
 
 # Getting Started
 
-GPUI Component is a comprehensive UI component library for building fantastic desktop applications using [GPUI](https://gpui.rs). It provides 40+ cross-platform components with modern design, theming support, and high performance.
-
-## Features
-
-- **Richness**: 40+ cross-platform desktop UI components
-- **Native**: Inspired by macOS and Windows controls, combined with shadcn/ui design
-- **Ease of Use**: Stateless `RenderOnce` components, simple and user-friendly
-- **Customizable**: Built-in `Theme` and `ThemeColor`, supporting multi-theme
-- **Versatile**: Supports sizes like `xs`, `sm`, `md`, and `lg`
-- **Flexible Layout**: Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts
-- **High Performance**: Virtualized Table and List components for smooth large-data rendering
-- **Content Rendering**: Native support for Markdown and simple HTML
-- **Charting**: Built-in charts for visualization
-- **Editor**: High performance code editor with LSP support
-- **Syntax Highlighting**: Using Tree Sitter
-
 ## Installation
 
 Add dependencies to your `Cargo.toml`:
@@ -81,11 +65,58 @@ fn main() {
 }
 ```
 
+:::info
+Make sure to call `gpui_component::init(cx);` at first line inside the `app.run` closure. This initializes the GPUI Component system.
+
+This is required for theming and other global settings to work correctly.
+:::
+
 ## Basic Concepts
 
-### Stateless Components
+### Stateless Elements
 
-GPUI Component uses stateless `RenderOnce` components, making them simple and predictable. State management is handled at the view level, not in individual components.
+GPUI Component uses stateless [RenderOnce] elements, making them simple and predictable. State management is handled at the view level, not in individual components.
+
+The are all implemented [IntoElement] types.
+
+For example:
+
+```rs
+struct MyView;
+
+impl Render for MyView {
+    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
+        div()
+            .child(Button::new("btn").label("Click Me"))
+            .child(Tag::secondary().child("Secondary"))
+    }
+}
+```
+
+### Stateful Components
+
+There are some stateful components like `Dropdown`, `List`, and `Table` that manage their own internal state for convenience, these components implement the [Render] trait.
+
+Those components to use are a bit different, we need create the [Entity] and hold it in the view struct.
+
+```rs
+struct MyView {
+    input: Entity<InputState>,
+}
+
+impl MyView {
+    fn new(window: &Window, cx: &mut Context<Self>) -> Self {
+        let input = cx.new(|cx| InputState::new(window, cx).default_value("Hello 世界"));
+        Self { input }
+    }
+}
+
+impl Render for MyView {
+    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
+        self.input.clone()
+    }
+}
+```
 
 ### Theming
 
@@ -160,3 +191,7 @@ More examples can be found in the `examples` directory:
 ```bash
 cargo run --example <example_name>
 ```
+
+[RenderOnce]: https://docs.rs/gpui/latest/gpui/trait.RenderOnce.html
+[IntoElement]: https://docs.rs/gpui/latest/gpui/trait.IntoElement.html
+[Render]: https://docs.rs/gpui/latest/gpui/trait.Render.html

docs/docs/index.md

@@ -7,57 +7,21 @@ description: Rust GUI components for building fantastic cross-platform desktop a
 
 GPUI Component is a Rust UI component library for building fantastic desktop applications using [GPUI](https://gpui.rs).
 
-## Getting Started
+GPUI Component is a comprehensive UI component library for building fantastic desktop applications using [GPUI](https://gpui.rs). It provides 40+ cross-platform components with modern design, theming support, and high performance.
-
-New to GPUI Component? Start here:
-
-- [Getting Started](./getting-started) - Installation, setup, and your first component
 
 ## Features
 
-### Richness
+- **Richness**: 40+ cross-platform desktop UI components
-
+- **Native**: Inspired by macOS and Windows controls, combined with shadcn/ui design
-40+ cross-platform desktop UI components for building comprehensive applications.
+- **Ease of Use**: Stateless `RenderOnce` components, simple and user-friendly
-
+- **Customizable**: Built-in `Theme` and `ThemeColor`, supporting multi-theme
-### Native
+- **Versatile**: Supports sizes like `xs`, `sm`, `md`, and `lg`
-
+- **Flexible Layout**: Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts
-Inspired by macOS and Windows controls, combined with modern shadcn/ui design for a native experience.
+- **High Performance**: Virtualized Table and List components for smooth large-data rendering
-
+- **Content Rendering**: Native support for Markdown and simple HTML
-### Ease of Use
+- **Charting**: Built-in charts for visualization
-
+- **Editor**: High performance code editor with LSP support
-Stateless `RenderOnce` components that are simple and user-friendly, following GPUI's design principles and Fluent API.
+- **Syntax Highlighting**: Using Tree Sitter
-
-### Customizable
-
-Built-in `Theme` and `ThemeColor` supporting multi-theme and variable-based configurations, and with built-in [20+ themes](https://github.com/longbridge/gpui-component/tree/main/themes).
-
-### 📏 Versatile
-
-Supports sizes like `xs`, `sm`, `md`, and `lg` across components.
-
-### Flexible Layout
-
-Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts.
-
-### High Performance
-
-Virtualized Table and List components for smooth rendering of large datasets.
-
-### Content Rendering
-
-Native support for Markdown and simple HTML rendering.
-
-### Charting
-
-Built-in charts for data visualization.
-
-### Editor
-
-High-performance code editor with LSP support (diagnostics, completion, hover).
-
-### Syntax Highlighting
-
-Powered by Tree Sitter for accurate syntax highlighting.
 
 ## Quick Example
 

docs/docs/root.md

@@ -0,0 +1,62 @@
+---
+order: -3
+---
+
+# Root View
+
+The [Root] component for as the root provider of GPUI Component features in a window. We must to use [Root] as the **first level child** of a window to enable GPUI Component features.
+
+This is important, if we don't use [Root] as the first level child of a window, there will have some unexpected behaviors.
+
+```rs
+fn main() {
+    let app = Application::new();
+
+    app.run(move |cx| {
+        // This must be called before using any GPUI Component features.
+        gpui_component::init(cx);
+
+        cx.spawn(async move |cx| {
+            cx.open_window(WindowOptions::default(), |window, cx| {
+                let view = cx.new(|_| Example);
+                // This first level on the window, should be a Root.
+                cx.new(|cx| Root::new(view.into(), window, cx))
+            })?;
+
+            Ok::<_, anyhow::Error>(())
+        })
+        .detach();
+    });
+}
+```
+
+## Overlays
+
+We have modals, drawers, notifications, we need placement for them to show, so [Root] provides methods to render these overlays:
+
+- [Root::render_modal_layer](https://docs.rs/gpui-component/latest/gpui_component/struct.Root.html#method.render_modal_layer) - Render the current opened modals.
+- [Root::render_drawer_layer](https://docs.rs/gpui-component/latest/gpui_component/struct.Root.html#method.render_drawer_layer) - Render the current opened drawers.
+- [Root::render_notification_layer](https://docs.rs/gpui-component/latest/gpui_component/struct.Root.html#method.render_notification_layer) - Render the notification list.
+
+We can put these layers in the `render` method your first level view (Root > YourFirstView):
+
+```rs
+struct MyApp;
+
+impl Render for MyApp {
+    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
+        div()
+            .size_full()
+            .child("My App Content")
+            .children(Root::render_modal_layer(cx))
+            .children(Root::render_drawer_layer(cx))
+            .children(Root::render_notification_layer(cx))
+    }
+}
+```
+
+:::tip
+Here the example we used `children` method, it because if there is no opened modals/drawers/notifications, these methods will return `None`, so GPUI will not render anything.
+:::
+
+[Root]: https://docs.rs/gpui-component/latest/gpui_component/root/struct.Root.html

docs/docs/theme.md

@@ -0,0 +1,52 @@
+---
+order: -4
+---
+
+# Theme
+
+All components support theming through the built-in Theme system, the [ActiveTheme] trait provides access to the current theme colors:
+
+```rs
+use gpui_component::{ActiveTheme as _};
+
+// Access theme colors in your components
+cx.theme().primary
+cx.theme().background
+cx.theme().foreground
+```
+
+So if you want use the colors from the current theme, you should keep your component or view have [App] context.
+
+## Theme Registry
+
+There have more than 20 built-in themes available in [themes](https://github.com/longbridge/gpui-component/tree/main/themes) folder.
+
+https://github.com/longbridge/gpui-component/tree/main/themes
+
+And we have a [ThemeRegistry] to help us to load themes.
+
+```rs
+use std::path::PathBuf;
+use gpui::{App, SharedString};
+use gpui_component::{Theme, ThemeRegistry};
+
+pub fn init(cx: &mut App) {
+    let theme_name = "Ayu Light";
+    // Load and watch themes from ./themes directory
+    if let Err(err) = ThemeRegistry::watch_dir(PathBuf::from("./themes"), cx, move |cx| {
+        if let Some(theme) = ThemeRegistry::global(cx)
+            .themes()
+            .get(&theme_name)
+            .cloned()
+        {
+            Theme::global_mut(cx).apply_config(&theme);
+        }
+    }) {
+        tracing::error!("Failed to watch themes directory: {}", err);
+    }
+}
+```
+
+[ActiveTheme]: https://docs.rs/gpui-component/latest/gpui_component/theme/trait.ActiveTheme.html
+[ThemeRegistry]: https://docs.rs/gpui-component/latest/gpui_component/theme/struct.ThemeRegistry.html
+[App]: https://docs.rs/gpui/latest/gpui/struct.App.html