Rework Guide

Cargo.toml

@@ -72,6 +72,7 @@ members = [
     "packages/native-core",
     "packages/native-core-macro",
     "packages/rsx-prelude",
+    "docs/guide",
 ]
 
 [dev-dependencies]

docs/guide/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "dioxus-guide"
+version = "0.0.1"
+edition = "2021"
+description = "Dioxus guide, including testable examples"
+license = "MIT/Apache-2.0"
+
+[dev-dependencies]
+dioxus = { path = "../..", features = ["desktop", "web", "ssr", "router", "fermi", "tui"] }
+serde = { version = "1.0.138", features=["derive"] }
+reqwest = { version = "0.11.11", features = ["json"] }
+tokio = { version = "1.19.2" , features=[]}

docs/guide/book.toml

@@ -1,6 +1,6 @@
 [book]
 title = "Dioxus Documentation"
-description = "Create book from markdown files. Like Gitbook but implemented in Rust"
+description = "Get started with Dioxus, a portable, performant, and ergonomic framework for building cross-platform user interfaces in Rust"
 authors = ["Jonathan Kelley"]
 language = "en"
 

docs/guide/examples/Readme.md

@@ -0,0 +1 @@
+Some of these examples (e.g. web) cannot be run. The code samples are here mostly so that we can easily check that they compile using `cargo test`.

docs/guide/examples/anti_patterns.rs

@@ -0,0 +1,71 @@
+#![allow(non_snake_case, unused)]
+
+//! This example shows what *not* to do
+
+use std::collections::HashMap;
+
+use dioxus::prelude::*;
+
+fn main() {}
+
+fn AntipatternNestedFragments(cx: Scope<()>) -> Element {
+    // ANCHOR: nested_fragments
+    // ❌ Don't unnecessarily nest fragments
+    let _ = cx.render(rsx!(
+        Fragment {
+            Fragment {
+                Fragment {
+                    Fragment {
+                        Fragment {
+                            div { "Finally have a real node!" }
+                        }
+                    }
+                }
+            }
+        }
+    ));
+
+    // ✅ Render shallow structures
+    cx.render(rsx!(
+        div { "Finally have a real node!" }
+    ))
+    // ANCHOR_END: nested_fragments
+}
+
+#[derive(PartialEq, Props)]
+struct NoKeysProps {
+    data: HashMap<u32, String>,
+}
+
+fn AntipatternNoKeys(cx: Scope<NoKeysProps>) -> Element {
+    // ANCHOR: iter_keys
+    let data: &HashMap<_, _> = &cx.props.data;
+
+    // ❌ No keys
+    cx.render(rsx! {
+        ul {
+            data.values().map(|value| rsx!(
+                li { "List item: {value}" }
+            ))
+        }
+    });
+
+    // ❌ Using index as keys
+    cx.render(rsx! {
+        ul {
+            cx.props.data.values().enumerate().map(|(index, value)| rsx!(
+                li { key: "{index}", "List item: {value}" }
+            ))
+        }
+    });
+
+    // ✅ Using unique IDs as keys:
+    cx.render(rsx! {
+        ul {
+            cx.props.data.iter().map(|(key, value)| rsx!(
+                li { key: "{key}", "List item: {value}" }
+            ))
+        }
+    })
+    // ANCHOR_END: iter_keys
+}

docs/guide/examples/boolean_attribute.rs

@@ -0,0 +1,17 @@
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App);
+}
+
+fn App(cx: Scope) -> Element {
+    // ANCHOR: boolean_attribute
+    cx.render(rsx! {
+        div {
+            hidden: "false",
+            "hello"
+        }
+    })
+    // ANCHOR_END: boolean_attribute
+}

docs/guide/examples/component_borrowed_props.rs

@@ -0,0 +1,27 @@
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App);
+}
+
+// ANCHOR: App
+fn App(cx: Scope) -> Element {
+    let hello = "Hello Dioxus!";
+
+    cx.render(rsx!(TitleCard { title: hello }))
+}
+// ANCHOR_END: App
+
+// ANCHOR: TitleCard
+#[derive(Props)]
+struct TitleCardProps<'a> {
+    title: &'a str,
+}
+
+fn TitleCard<'a>(cx: Scope<'a, TitleCardProps<'a>>) -> Element {
+    cx.render(rsx! {
+        h1 { "{cx.props.title}" }
+    })
+}
+// ANCHOR_END: TitleCard

docs/guide/examples/component_children.rs

@@ -0,0 +1,36 @@
+// ANCHOR: all
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App);
+}
+
+fn App(cx: Scope) -> Element {
+    // ANCHOR: Clickable_usage
+    cx.render(rsx! {
+        Clickable {
+            href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",
+            "How to " i {"not"} " be seen"
+        }
+    })
+    // ANCHOR_END: Clickable_usage
+}
+
+// ANCHOR: Clickable
+#[derive(Props)]
+struct ClickableProps<'a> {
+    href: &'a str,
+    children: Element<'a>,
+}
+
+fn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {
+    cx.render(rsx!(
+        a {
+            href: "{cx.props.href}",
+            class: "fancy-button",
+            &cx.props.children
+        }
+    ))
+}
+// ANCHOR_END: Clickable

docs/guide/examples/component_children_inspect.rs

@@ -0,0 +1,37 @@
+// ANCHOR: all
+#![allow(non_snake_case, unused)]
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App);
+}
+
+fn App(cx: Scope) -> Element {
+    // ANCHOR: Clickable_usage
+    cx.render(rsx! {
+        Clickable {
+            href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",
+            "How to " i {"not"} " be seen"
+        }
+    })
+    // ANCHOR_END: Clickable_usage
+}
+
+#[derive(Props)]
+struct ClickableProps<'a> {
+    href: &'a str,
+    children: Element<'a>,
+}
+
+// ANCHOR: Clickable
+fn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {
+    match cx.props.children {
+        Some(VNode::Text(_)) => {
+            todo!("render some stuff")
+        }
+        _ => {
+            todo!("render some other stuff")
+        }
+    }
+}
+// ANCHOR_END: Clickable

docs/guide/examples/component_element_props.rs

@@ -0,0 +1,36 @@
+// ANCHOR: all
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App);
+}
+
+fn App(cx: Scope) -> Element {
+    // ANCHOR: Clickable_usage
+    cx.render(rsx! {
+        Clickable {
+            href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",
+            body: cx.render(rsx!("How to " i {"not"} " be seen")),
+        }
+    })
+    // ANCHOR_END: Clickable_usage
+}
+
+// ANCHOR: Clickable
+#[derive(Props)]
+struct ClickableProps<'a> {
+    href: &'a str,
+    body: Element<'a>,
+}
+
+fn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {
+    cx.render(rsx!(
+        a {
+            href: "{cx.props.href}",
+            class: "fancy-button",
+            &cx.props.body
+        }
+    ))
+}
+// ANCHOR_END: Clickable

docs/guide/examples/component_owned_props.rs

@@ -0,0 +1,34 @@
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App);
+}
+
+// ANCHOR: App
+fn App(cx: Scope) -> Element {
+    cx.render(rsx! {
+        Likes {
+            score: 42,
+        },
+    })
+}
+// ANCHOR_END: App
+
+// ANCHOR: Likes
+// Remember: Owned props must implement `PartialEq`!
+#[derive(PartialEq, Props)]
+struct LikesProps {
+    score: i32,
+}
+
+fn Likes(cx: Scope<LikesProps>) -> Element {
+    cx.render(rsx! {
+        div {
+            "This post has ",
+            b { "{cx.props.score}" },
+            " likes"
+        }
+    })
+}
+// ANCHOR_END: Likes