docs: big updates to the reference

Author: jkelleyrtp

Cargo.toml

@@ -19,7 +19,7 @@ dioxus-mobile = { path = "./packages/mobile", optional = true }
 
 [features]
 # core
-default = ["core"]
+default = ["core", "ssr"]
 core = ["macro", "hooks", "html"]
 macro = ["dioxus-core-macro"]
 hooks = ["dioxus-hooks"]
@@ -48,6 +48,7 @@ async-std = { version = "1.9.0", features = ["attributes"] }
 im-rc = "15.0.0"
 rand = { version = "0.8.4", features = ["small_rng"] }
 fxhash = "0.2.1"
+gloo-timers = "0.2.1"
 
 [workspace]
 members = [

docs/main-concepts/03-rsx.md

@@ -60,7 +60,7 @@ Commas are entirely optional, but might be useful to delineate between elements
 The `render` function provides an **extremely efficient** allocator for VNodes and text, so try not to use the `format!` macro in your components. Rust's default `ToString` methods pass through the global allocator, but all text in components is allocated inside a manually-managed Bump arena. To push you in the right direction, all text-based attributes take `std::fmt::Arguments` directly, so you'll want to reach for `format_args!` when the built-in `f-string` interpolation just doesn't cut it.
 
 ```rust
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
 
     let text = "example";
 

docs/platforms/06-components.md

@@ -25,7 +25,7 @@ fn Example(cx: Context, name: String) -> VNode {
 // or
 
 #[functional_component]
-static Example: FC = |cx, name: String| html! { <div> "Hello {name}!" </div> };
+pub static Example: FC = |cx, name: String| html! { <div> "Hello {name}!" </div> };
 ```
 
 The final output of components must be a tree of VNodes. We provide an html macro for using JSX-style syntax to write these, though, you could use any macro, DSL, templating engine, or the constructors directly.

examples/_examples/context.rs

@@ -25,7 +25,7 @@ fn main() {
 #[derive(Debug)]
 struct CustomContext([&'static str; 3]);
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.use_create_context(|| CustomContext(["Jack", "Jill", "Bob"]));
 
     cx.render(rsx! {

examples/_examples/hello.rs

@@ -13,7 +13,7 @@ fn main() {
     wasm_bindgen_futures::spawn_local(WebsysRenderer::start(Example));
 }
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     let nodes = (0..500).map(|f| rsx! (li {"div"}));
     cx.render(rsx! {
         div {

examples/_examples/infer.rs

@@ -14,7 +14,7 @@ fn main() {
 }
 
 // this is a component
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     let (event, set_event) = use_state_classic(cx, || None);
 
     let handler = move |evt| {
@@ -50,7 +50,7 @@ struct ExampleProps {
     name: String,
 }
 
-static Example2: FC<ExampleProps> = |cx| {
+pub static Example2: FC<ExampleProps> = |cx| {
     cx.render(rsx! {
         div {
             h1 {"hello {cx.name}"}

examples/_examples/input.rs

@@ -37,7 +37,7 @@ static App: FC<()> = |cx| {
     })
 };
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.render(rsx! {
         div { class: "max-w-lg max-w-xs bg-blue-800 shadow-2xl rounded-lg mx-auto text-center py-12 mt-4 rounded-xl"
             div { class: "container py-5 max-w-md mx-auto"

examples/_examples/jackjill.rs

@@ -9,7 +9,7 @@ fn main() {
     wasm_bindgen_futures::spawn_local(WebsysRenderer::start(Example))
 }
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     let (name, set_name) = use_state_classic(cx, || "...?");
 
     log::debug!("Running component....");

examples/_examples/jackjillrsx.rs

@@ -9,7 +9,7 @@ fn main() {
     wasm_bindgen_futures::spawn_local(WebsysRenderer::start(Example))
 }
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     let (name, set_name) = use_state_classic(cx, || "...?");
     cx.render(rsx! {
         section { class: "py-12 px-4 text-center"

examples/_examples/many.rs

@@ -11,7 +11,7 @@ fn main() {
     wasm_bindgen_futures::spawn_local(WebsysRenderer::start(Example));
 }
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.render(rsx! {
         div {
             span {

examples/_examples/rsxt.rs

@@ -27,7 +27,7 @@ struct ExampleProps {
     initial_name: &'static str,
 }
 
-static Example: FC<ExampleProps> = |cx| {
+pub static Example: FC<ExampleProps> = |cx| {
     let name = use_state(cx, move || cx.initial_name);
 
     cx.render(rsx! {

examples/doggo.rs

@@ -1,7 +1,7 @@
 use dioxus::prelude::*;
 fn main() {}
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     let (g, set_g) = use_state(cx, || 0).classic();
     let v = (0..10).map(move |f| {
         rsx!(li {

examples/examples/demo.rs

@@ -17,7 +17,7 @@ fn main() {
     .expect("Webview finished");
 }
 
-// static Example: FC<()> = |cx| {
+// pub static Example: FC<()> = |cx| {
 //     cx.render(html! {
 //         <div>
 //         <svg class="octicon octicon-star v-align-text-bottom"
@@ -36,7 +36,7 @@ fn main() {
 //         </div>
 //     })
 // };
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.render(rsx! {
         div  {
             class: "flex items-center justify-center flex-col"

examples/model.rs

@@ -20,12 +20,8 @@ use dioxus::prelude::*;
 
 const STYLE: &str = include_str!("./assets/calculator.css");
 fn main() {
-    dioxus::desktop::launch(App, |cfg| {
-        cfg.with_title("Calculator Demo")
-            .with_resizable(true)
-            .with_skip_taskbar(true)
-    })
-    .expect("failed to launch dioxus app");
+    dioxus::desktop::launch(App, |cfg| cfg.with_title("Calculator Demo"))
+        .expect("failed to launch dioxus app");
 }
 
 static App: FC<()> = |cx| {

examples/reference/antipatterns.rs

@@ -16,8 +16,6 @@
 //! Feel free to file a PR or Issue if you run into another antipattern that you think users of Dioxus should know about.
 use dioxus::prelude::*;
 
-fn main() {}
-
 /// Antipattern: Iterators without keys
 /// -----------------------------------
 ///
@@ -174,3 +172,10 @@ static _example: FC<()> = |cx| todo!();
 /// This will only include the `core` dioxus crate which is relatively slim and fast to compile and avoids target-specific
 /// libraries.
 static __example: FC<()> = |cx| todo!();
+
+pub static Example: FC<()> = |cx| {
+    cx.render(rsx! {
+        AntipatternNoKeys { data: std::collections::HashMap::new() }
+        AntipatternNestedFragments {}
+    })
+};

examples/reference/async.rs

@@ -1,10 +1,37 @@
+//! Example: The basics of Dioxus
+//! ----------------------------
+//!
+//! This small example covers some of the basics of Dioxus including
+//! - Components
+//! - Props
+//! - Children
+//! - the rsx! macro
+
 use dioxus::prelude::*;
-fn main() {}
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.render(rsx! {
         div {
+            Greeting {
+                name: "Dioxus"
+                div { "Dioxus is a fun, fast, and portable UI framework for Rust" }
+            }
+        }
+    })
+};
 
+#[derive(PartialEq, Props)]
+struct GreetingProps {
+    name: &'static str,
+}
+
+static Greeting: FC<GreetingProps> = |cx| {
+    cx.render(rsx! {
+        div {
+            h1 { "Hello, {cx.name}!" }
+            p { "Welcome to the Diouxs framework" }
+            br {}
+            {cx.children()}
         }
     })
 };

examples/reference/basics.rs

@@ -17,9 +17,8 @@
 //! In the future, this might become a runtime error, so consider it an error today.
 
 use dioxus::prelude::*;
-fn main() {}
 
-static App: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.render(rsx! {
         div {
             Banner {
@@ -32,7 +31,7 @@ static App: FC<()> = |cx| {
     })
 };
 
-static Banner: FC<()> = |cx| {
+pub static Banner: FC<()> = |cx| {
     cx.render(rsx! {
         div {
             h1 { "This is a great banner!" }

examples/reference/children.rs

@@ -11,14 +11,12 @@
 
 use dioxus::prelude::*;
 
-fn main() {}
-
 // Convert a boolean conditional into a hide/show
 #[derive(PartialEq, Props)]
-struct MyProps {
+pub struct MyProps {
     should_show: bool,
 }
-static Example: FC<MyProps> = |cx| {
+pub static Example0: FC<MyProps> = |cx| {
     cx.render(rsx! {
         div {
             {cx.should_show.then(|| rsx!{
@@ -38,10 +36,10 @@ static Example: FC<MyProps> = |cx| {
 // In short:
 // `rsx!(in cx, ...)` is shorthand for `cx.render(rsx!(...))`
 #[derive(PartialEq, Props)]
-struct MyProps1 {
+pub struct MyProps1 {
     should_show: bool,
 }
-static Example1: FC<MyProps1> = |cx| {
+pub static Example1: FC<MyProps1> = |cx| {
     cx.render(rsx! {
         div {
             // With matching
@@ -70,16 +68,16 @@ static Example1: FC<MyProps1> = |cx| {
 /// Matching can be expanded
 
 #[derive(PartialEq)]
-enum Color {
+pub enum Color {
     Green,
     Yellow,
     Red,
 }
 #[derive(PartialEq, Props)]
-struct MyProps2 {
+pub struct MyProps2 {
     color: Color,
 }
-static Example2: FC<MyProps2> = |cx| {
+pub static Example2: FC<MyProps2> = |cx| {
     cx.render(rsx! {
         div {
             {match cx.color {
@@ -90,3 +88,29 @@ static Example2: FC<MyProps2> = |cx| {
         }
     })
 };
+
+pub static Example: FC<()> = |cx| {
+    let should_show = use_state(cx, || false);
+    let mut color_index = use_state(cx, || 0);
+    let color = match *color_index % 2 {
+        2 => Color::Green,
+        1 => Color::Yellow,
+        _ => Color::Red,
+    };
+
+    cx.render(rsx! {
+        div {
+            button {
+                onclick: move |_| should_show.set(!*should_show)
+                "click to toggle showing the examples"
+            }
+            button {
+                onclick: move |_| color_index += 1
+                "click to for the enxt color"
+            }
+            Example0 { should_show: *should_show }
+            Example1 { should_show: *should_show }
+            Example2 { color: color }
+        }
+    })
+};

examples/reference/conditional_rendering.rs

@@ -1,10 +1,37 @@
 use dioxus::prelude::*;
 fn main() {}
 
-static Example: FC<()> = |cx| {
+pub static Example: FC<()> = |cx| {
     cx.render(rsx! {
         div {
 
         }
     })
 };
+
+// A controlled component:
+static ControlledSelect: FC<()> = |cx| {
+    let value = use_state(cx, || String::from("Grapefruit"));
+    cx.render(rsx! {
+        select { value: "{value}", onchange: move |evt| value.set(evt.value()),
+            option { value: "Grapefruit", "Grapefruit"}
+            option { value: "Lime", "Lime"}
+            option { value: "Coconut", "Coconut"}
+            option { value: "Mango", "Mango"}
+        }
+    })
+};
+
+// TODO - how do uncontrolled things work?
+static UncontrolledSelect: FC<()> = |cx| {
+    let value = use_state(cx, || String::new());
+
+    cx.render(rsx! {
+        select {
+            option { value: "Grapefruit", "Grapefruit"}
+            option { value: "Lime", "Lime"}
+            option { value: "Coconut", "Coconut"}
+            option { value: "Mango", "Mango"}
+        }
+    })
+};