docs: improve docs

README.md

@@ -49,7 +49,7 @@
 Dioxus is a portable, performant, and ergonomic framework for building cross-platform user experiences in Rust.
 
 ```rust
-static App: FC<()> = |(cx, props)| {
+fn App((cx, props): Component<()>) -> Element {
     let mut count = use_state(cx, || 0);
 
     cx.render(rsx!(

docs/src/README.md

@@ -5,8 +5,7 @@
 **Dioxus** is a framework and ecosystem for building fast, scalable, and robust user interfaces with the Rust programming language. This guide will help you get up-and-running with Dioxus running on the Web, Desktop, Mobile, and more. 
 
 ```rust
-// An example Dioxus app - closely resembles React
-fn App(cx: Component<()>) -> Element {
+fn App((cx, props): Component<()>) -> Element {
     let mut count = use_state(cx, || 0);
 
     cx.render(rsx!(
@@ -20,7 +19,6 @@ fn App(cx: Component<()>) -> Element {
 The Dioxus API and patterns closely resemble React - if this guide is lacking in any general concept or an error message is confusing, we recommend substituting "React" for "Dioxus" in your web search terms. A major goal of Dioxus is to provide a familiar toolkit for UI in Rust, so we've chosen to follow in the footsteps of popular UI frameworks (React, Redux, etc) - if you know React, then you already know Dioxus. If you don't know either, this guide will still help you!
 
 
-
 ### Web Support
 ---
 
@@ -79,23 +77,27 @@ Examples:
 ---
 Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with the platform's WebView, meaning that animations, transparency, and native widgets are not currently achievable. In addition, iOS is the only supported Mobile Platform. It is possible to get Dioxus running on Android and rendered with WebView, but the Rust windowing library that Dioxus uses - tao - does not currently supported Android.
 
+Mobile support is currently best suited for CRUD-style apps, ideally for internal teams who need to develop quickly but don't care much about animations or native widgets.
+
 [Jump to the getting started guide for Mobile.]()
 
 Examples:
 - [Todo App]()
 - [Chat App]()
 
-### LiveView Support
+### LiveView / Server Component Support
 ---
 
-The internal architecture of Dioxus was designed from day one to support the `LiveView` use-case, where a web server hosts a running app for each connected user. As of today, there is no out-of-the-box LiveView support - you'll need to wire this up yourself. While not currently fully implemented, the expectation is that LiveView apps can be a hybrid between WASM and server-rendered where only portions of a page are "live" and the rest of the page is either server-rendered, statically generated, or handled by the host SPA.
-
+The internal architecture of Dioxus was designed from day one to support the `LiveView` use-case, where a web server hosts a running app for each connected user. As of today, there is no first-class LiveView support - you'll need to wire this up yourself. 
 
+While not currently fully implemented, the expectation is that LiveView apps can be a hybrid between Wasm and server-rendered where only portions of a page are "live" and the rest of the page is either server-rendered, statically generated, or handled by the host SPA.
 
 ### Multithreaded Support
 ---
-The Dioxus VirtualDom, sadly, is not currently `Send.` Internally, we use quite a bit of interior mutability which is not thread-safe. This means you can't easily use Dioxus with most web frameworks like Tide, Rocket, Axum, etc. 
+The Dioxus VirtualDom, sadly, is not currently `Send`. Internally, we use quite a bit of interior mutability which is not thread-safe. This means you can't easily use Dioxus with most web frameworks like Tide, Rocket, Axum, etc. 
 
 To solve this, you'll want to spawn a VirtualDom on its own thread and communicate with it via channels.
 
-When working with web frameworks that require `Send`, it is possible to render a VirtualDom immediately to a String - but you cannot hold the VirtualDom across an await point. For retained-state SSR (essentially LiveView), you'll need to create a VirtualDomPool which solves the `Send` problem.
+When working with web frameworks that require `Send`, it is possible to render a VirtualDom immediately to a String - but you cannot hold the VirtualDom across an await point. For retained-state SSR (essentially LiveView), you'll need to create a pool of VirtualDoms.
+
+Ultimately, you can always wrap the VirtualDom with a `Send` type and manually uphold the `Send` guarantees yourself.

docs/src/SUMMARY.md

@@ -3,22 +3,47 @@
 - [Introduction](README.md)
 - [Getting Setup](setup.md)
 - [Hello, World!](hello_world.md)
-- [Core Topics](concepts/00-index.md)
-    - [Intro to Elements](concepts/vnodes.md)
-    - [Intro to Components](concepts/components.md)
-    - [Elements with RSX and NodeFactory](concepts/rsx.md)
-    - [RSX in Depth](concepts/rsx_in_depth.md)
-    - [Memoization](concepts/memoization.md)
-    - [Hooks and Internal State](concepts/hooks.md)
-    - [Event handlers](concepts/event_handlers.md)
-    - [Global State](concepts/sharedstate.md)
-    - [User Input and Controlled Components](concepts/errorhandling.md)
-    - [Error handling](concepts/errorhandling.md)
-- [Reference Guide]()
-- [Advanced Guides]()
-  - [Custom Renderer]()
-  - [LiveView Support]()
-  - [Bundling and Distributing]()
+- [Describing the UI](concepts/00-index.md)
+  - [Intro to Elements](concepts/vnodes.md)
+  - [Intro to Components](concepts/components.md)
+  - [Reusing, Importing, and Exporting Components](concepts/exporting_components.md)
+  - [Conditional Rendering](concepts/conditional_rendering.md)
+  - [Lists](concepts/lists.md)
+- [Adding Interactivity](concepts/interactivity.md)
+  - [Event handlers](concepts/event_handlers.md)
+  - [User Input and Controlled Components](concepts/errorhandling.md)
+  - [Lifecycle, updates, and effects](concepts/lifecycles.md)
+- [Managing State](concepts/managing_state.md)
+  - [Hooks and Internal State](concepts/hooks.md)
+  - [Global State](concepts/sharedstate.md)
+  - [Error handling](concepts/errorhandling.md)
+  - [Effects](concepts/effects.md)
+- [Working with Async](concepts/async.md)
+  - [Tasks](concepts/asynctasks.md)
+  - [Suspense](concepts/suspense.md)
+  - [Async Callbacks](concepts/asynccallbacks.md)
+- [Putting it all together](tutorial/index.md)
+  - [New app](tutorial/new_app.md)
+  - [Structuring our app](tutorial/structure.md)
+  - [Defining State](tutorial/state.md)
+  - [Defining Components](tutorial/components.md)
+  - [Styling](tutorial/styling.md)
+  - [Publishing](tutorial/publishing.md)
+- [Topics in Depth](depth/topics.md)
+  - [RSX](depth/rsx.md)
+  - [Components](depth/components.md)
+  - [Props](depth/props.md)
+  - [Memoization](depth/memoization.md)
+  - [Performance](depth/performance.md)
+  - [Testing](depth/testing.md)
+- [Advanced Guides](tutorial/advanced_guides.md)
+  - [Memoization](concepts/memoization.md)
+  - [RSX in Depth](concepts/rsx_in_depth.md)
+  - [Building Elements with NodeFactory](concepts/rsx.md)
+  - [Custom Elements](concepts/custom_elements.md)
+  - [Custom Renderer](concepts/custom_renderer.md)
+  - [Server-side components](concepts/server_side_components.md)
+  - [Bundling and Distributing](concepts/bundline.md)
 - [Web]()
   - [Getting Started]()
   - [Down-casting Nodes]()
@@ -29,33 +54,26 @@
   - [Wrapping Web APIs]()
 - [Mobile]()
   - [Wrapping Web APIs]()
-
-
-<!-- - [Command Line Tool](cli/README.md)
-    - [init](cli/init.md)
-    - [build](cli/build.md)
-    - [watch](cli/watch.md)
-    - [serve](cli/serve.md)
-    - [test](cli/test.md)
-    - [clean](cli/clean.md)
-- [Format](format/README.md)
-    - [SUMMARY.md](format/summary.md)
-        - [Draft chapter]()
-    - [Configuration](format/configuration/README.md)
-        - [General](format/configuration/general.md)
-        - [Preprocessors](format/configuration/preprocessors.md)
-        - [Renderers](format/configuration/renderers.md)
-        - [Environment Variables](format/configuration/environment-variables.md)
-    - [Theme](format/theme/README.md)
-        - [index.hbs](format/theme/index-hbs.md)
-        - [Syntax highlighting](format/theme/syntax-highlighting.md)
-        - [Editor](format/theme/editor.md)
-    - [MathJax Support](format/mathjax.md)
-    - [mdBook-specific features](format/mdbook.md)
-- [Continuous Integration](continuous-integration.md)
-- [For Developers](for_developers/README.md)
-    - [Preprocessors](for_developers/preprocessors.md)
-    - [Alternative Backends](for_developers/backends.md) -->
+- [Reference Guide]()
+  - [Anti-patterns]()
+  - [Children]()
+  - [Conditional Rendering]()
+  - [Controlled Inputs]()
+  - [Custom Elements]()
+  - [Empty Components]()
+  - [Error Handling]()
+  - [Fragments]()
+  - [Global CSS]()
+  - [Inline Styles]()
+  - [Iterators]()
+  - [Listeners]()
+  - [Memoization]()
+  - [Node Refs]()
+  - [Spread Pattern]()
+  - [State Management]()
+  - [Suspense]()
+  - [task]()
+  - [Testing]()
 
 -----------
 

docs/src/cli/README.md

@@ -1 +0,0 @@
-# Command Line Tool

docs/src/cli/build.md

@@ -1 +0,0 @@
-# build

docs/src/cli/clean.md

@@ -1 +0,0 @@
-# clean

docs/src/cli/init.md

@@ -1 +0,0 @@
-# init

docs/src/cli/serve.md

@@ -1 +0,0 @@
-# serve

docs/src/cli/test.md

@@ -1 +0,0 @@
-# test

docs/src/cli/watch.md

@@ -1 +0,0 @@
-# watch

docs/src/concepts/04-hooks.md

@@ -1,16 +0,0 @@
-```rust
-fn Example<'a>(cx: Context<'a>, props: &()) -> DomTree<'a> {
-    let service = use_combubulator(cx);
-    let Status { name, pending, count } = service.info();
-    html! {
-        <div>
-            <p> "Hello, {name}!" </p>
-            <p> "Status: {pending}!" </p>
-            <p> "Count {count}!" </p>
-            <button onclick={|_| service.update()}>
-                "Refresh services"
-            </button>
-        </div>
-    }
-}
-```

docs/src/concepts/05-context-api.md

@@ -1,45 +0,0 @@
-# Context API
-
-```rust
-// Create contexts available to children
-// Only one context can be associated with any given component
-// This is known as "exposed state". Children can access this context,
-// but will not be automatically subscribed.
-fn ContextCreate(cx: &mut Context<()>) -> DomTree {
-    let context = cx.set_context(|| CustomContext::new());
-    html! { <> {cx.children()} </> }
-}
-
-fn ContextRead(cx: &mut Context<()>) -> DomTree {
-    // Panics if context is not available
-    let some_cx = cx.get_context::<CustomContext>();
-    let text = some_cx.select("some_selector");
-    html! { <div> "{text}" </div> }
-}
-
-fn Subscription(cx: &mut Context<()>) -> DomTree {
-    // Open a "port" on the component for actions to trigger a re-evaluation
-    let subscription = cx.new_subscription();
-
-    // A looping timer - the effect is re-called on every re-evaluation
-    use_async_effect(cx, move || async {
-        timer::new(2000).await;
-        subscription.call();
-    }, None);
-
-    // A one-shot timer, the deps don't change so the effect only happens once
-    use_async_effect_deps(cx, move || async {
-        timer::new(2000).await;
-        subscription.call();
-    }, ());
-}
-
-// Mix subscriptions and context to make a simple Redux
-fn use_global_state<T: UserContextTrait>(cx: &mut Context<()>) -> T {
-    let some_cx = cx.get_context::<T>();
-    let component_subscription = cx.new_subscription();
-    some_cx.subscribe_component(component_subscription);
-    some_cx
-}
-
-```

docs/src/concepts/9901-hello-world.md

@@ -1,18 +0,0 @@
-# Hello, World!
-
-Dioxus should look and feel just like writing functional React components. In Dioxus, there are no class components with lifecycles. All state management is done via hooks. This encourages logic reusability and lessens the burden on Dioxus to maintain a non-breaking lifecycle API.
-
-```rust
-#[derive(Properties, PartialEq)]
-struct MyProps {
-    name: String
-}
-
-fn Example(cx: Context<MyProps>) -> DomTree {
-    cx.render(html! {
-        <div> "Hello {cx.name}!" </div>
-    })
-}
-```
-
-For functions to be valid components, they must take the `Context` object which is generic over some properties. The properties parameter must implement the `Properties` trait, which can be automatically derived. Whenever the input properties of a component changes, the function component will be re-ran and a new set of VNodes will be generated.

docs/src/concepts/async.md

@@ -0,0 +1 @@
+# Working with Async

docs/src/concepts/asynccallbacks.md

@@ -0,0 +1 @@
+# Async Callbacks

docs/src/concepts/asynctasks.md

@@ -0,0 +1 @@
+# Tasks

docs/src/concepts/bundline.md

@@ -0,0 +1 @@
+# Bundling and Distributing

docs/src/concepts/components.md

@@ -6,26 +6,176 @@ In the previous chapter, we learned about Elements and how they can be composed
 
 In short, a component is a special function that takes an input and outputs a group of Elements. Typically, Components serve a single purpose: group functionality of a User Interface. Much like a function encapsulates some specific computation task, a Component encapsulates some specific rendering task.
 
-Let's take the r/rust subreddit page and see if we can identify some parts of the page that are encapsulated as a single rendering task.
+### Learning through prior art
 
+Let's take a look at a post on r/rust and see if we can sketch out a component representation.
 
-<!-- todo -->
+![Reddit Post](../images/reddit_post.png)
 
+This component has a bunch of important information:
 
+- The score
+- The number of comments
+- How long ago it was posted
+- The url short address
+- The title
+- The username of the original poster
 
-Dioxus should look and feel just like writing functional React components. In Dioxus, there are no class components with lifecycles. All state management is done via hooks. This encourages logic reusability and lessens the burden on Dioxus to maintain a non-breaking lifecycle API.
+If we wanted to sketch out these requirements in Rust, we would start with a struct:
 
+```rust
+struct Post {
+    score: i32,
+    comment_count: u32,
+    post_time: Instant,
+    url: String,
+    title: String,
+    original_poster_name: String
+}
+```
+
+If we look at the layout of the component, we notice quite a few buttons and functionality:
+
+- Upvote/Downvote
+- View comments
+- Share
+- Save
+- Hide
+- Give award
+- Report
+- Crosspost
+- Filter by site
+- View article
+- Visit user 
+
+If we included all this functionality in one `rsx!` call, it would be huge! Instead, let's break the post down into some core pieces:
+
+![Post as Component](../images/reddit_post_components.png)
+
+- **VoteButtons**: Upvote/Downvote
+- **TitleCard**: Title, Filter-By-Url
+- **MetaCard**: Original Poster, Time Submitted
+- **ActionCard**: View comments, Share, Save, Hide, Give award, Report, Crosspost
+
+### Modeling with Dioxus
+
+When designing these components, we can start by sketching out the hierarchy using Dioxus. In general, our "Post" component will simply be comprised of our four sub-components. We would start the process by defining our "Post" component. Our component will take in all of the important data we listed above as part of its input.
+
+Unlike normal functions, Dioxus components must explicitly define a single struct to contain all the inputs. These are commonly called "Properties" (props). Our component will be a combination of these properties and a function to render them.
+
+Our props must implement the `Properties` trait and - if the component does not borrow any data - `PartialEq`. Both of these can be done automatically through derive macros:
 ```rust
 #[derive(Properties, PartialEq)]
-struct MyProps {
-    name: String
+struct PostProps {
+    id: Uuid,
+    score: i32,
+    comment_count: u32,
+    post_time: Instant,
+    url: String,
+    title: String,
+    original_poster: String
+}
+```
+
+And our render function:
+```rust
+fn Post((cx, props): Component<PostProps>) -> Element {
+    cx.render(rsx!{
+        div { class: "post-container"
+            VoteButtons {
+                score: props.score,
+            }
+            TitleCard {
+                title: props.title,
+                url: props.url,
+            }
+            MetaCard {
+                original_poster: props.original_poster,
+                post_time: props.post_time,
+            }
+            ActionCard {
+                post_id: props.id
+            }
+        }
+    })
+}
+```
+
+When we render components, we use the traditional Rust struct syntax to declare their properties. Dioxus will automatically call "into" on the property fields, cloning when necessary. Notice how our `Post` component is simply a collection of important smaller components wrapped together in a single container.
+
+Let's take a look at the `VoteButtons` component. For now, we won't include any interactivity - just the rendering the vote buttons and score to the screen.
+
+Most of your Components will look exactly like this: a Props struct and a render function. As covered before, we'll build our User Interface with the `rsx!` macro and HTML tags. However, with components, we must actually "render" our HTML markup. Calling `cx.render` converts our "lazy" `rsx!` structure into an `Element`. Every component must take a tuple of `Context` and `&Props` and return an `Element`.
+```rust
+
+#[derive(PartialEq, Props)]
+struct VoteButtonsProps {
+    score: i32
+}
+
+fn VoteButtons((cx, props): Component<VoteButtonsProps>) -> Element {
+    cx.render(rsx!{
+        div { class: "votebuttons"
+            div { class: "arrow up" }
+            div { class: "score", "{props.score}"}
+            div { class: "arrow down" }
+        }
+    })
+}
+```
+
+## Borrowing
+
+You can avoid clones using borrowed component syntax. For example, let's say we passed the TitleCard title as an `&str` instead of `String`. In JavaScript, the string would simply be copied by reference - none of the contents would be copied, but rather the reference to the string's contents are copied. In Rust, this would be similar to calling `clone` on `Rc<str>`.
+
+Because we're working in Rust, we can choose to either use `Rc<str>`, clone `Title` on every re-render of `Post`, or simply borrow it. In most cases, you'll just want to let `Title` be cloned. 
+
+To enable borrowed values for your component, we need to add a lifetime to let the Rust compiler know that the output `Element` borrows from the component's props.
+
+```rust
+#[derive(Properties)]
+struct TitleCardProps<'a> {
+    title: &'a str,
+}
+
+fn TitleCard<'a>((cx, props): Component<'a, TitleCardProps>) -> Element<'a> {
+    cx.render(rsx!{
+        h1 { "{props.title}" }
+    })
+}   
+```
+
+## The `Context` object
+
+Though very similar with React, Dioxus is different in a few ways. Most notably, React components will not have a `Context` parameter in the component declaration. 
+
+Have you ever wondered how the `useState()` call works in React without a `this` object to actually store the state? 
+
+React uses global variables to store this information which must be carefully managed, especially in environments with multiple React roots - like the server.
+
+```javascript
+function Component({}) {
+    let [state, set_state] = useState(10);
 }
+```
 
-fn Example(cx: Context<MyProps>) -> DomTree {
-    html! { <div> "Hello {cx.props.name}!" </div> }
+
+Because Dioxus needs to work with the rules of Rust, we need to provide a way for the component to do some internal bookkeeping. That's what the `Context` object is: a place for the component to store state, manage listeners, and allocate elements. Advanced users of Dioxus will want to learn how to properly leverage the `Context` object to build robust, performant extensions for Dioxus.
+
+```rust
+fn Post((cx /* <-- our Context object*/, props): Component<PostProps>) -> Element {
+    cx.render(rsx!{ })
 }
 ```
 
-Here, the `Context` object is used to access hook state, create subscriptions, and interact with the built-in context API. Props, children, and component APIs are accessible via the `Context` object. The functional component macro makes life more productive by inlining props directly as function arguments, similar to how Rocket parses URIs.
+## Moving forward
+
+Next chapter, we'll talk about composing Elements and Components across files to build a larger Dioxus App.
+
+For more references on components, make sure to check out:
+
+- [Components in depth]()
+- [Lifecycles]()
+- [The Context object]()
+- [Optional Prop fields]()
 
-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.

docs/src/concepts/conditional_rendering.md

@@ -0,0 +1 @@
+# Conditional Rendering

docs/src/concepts/custom_elements.md

@@ -0,0 +1 @@
+# Custom Elements

docs/src/concepts/custom_renderer.md

@@ -0,0 +1 @@
+# Custom Renderer

docs/src/concepts/effects.md

@@ -0,0 +1 @@
+# Effects

docs/src/concepts/exporting_components.md

@@ -0,0 +1,291 @@
+
+# Reusing, Importing, and Exporting Components
+
+As your application grows in size, you'll want to start breaking your UI into components and, eventually, different files. This is a great idea to encapsulate functionality of your UI and scale your team.
+
+Let's say our app looks something like this:
+
+```shell
+├── Cargo.toml
+└── src
+    └── main.rs
+```
+
+```rust
+// main.rs
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App, |c| c);
+}
+
+fn App((cx, props): Component<()>) -> Element {} 
+
+#[derive(PartialEq, Props)]
+struct PostProps{}
+fn Post((cx, props): Component<PostProps>) -> Element {} 
+
+#[derive(PartialEq, Props)]
+struct VoteButtonsProps {}
+fn VoteButtons((cx, props): Component<VoteButtonsProps>) -> Element {} 
+
+#[derive(PartialEq, Props)]
+struct TitleCardProps {}
+fn TitleCard((cx, props): Component<TitleCardProps>) -> Element {} 
+
+#[derive(PartialEq, Props)]
+struct MetaCardProps {}
+fn MetaCard((cx, props): Component<MetaCardProps>) -> Element {} 
+
+#[derive(PartialEq, Props)]
+struct ActionCardProps {}
+fn ActionCard((cx, props): Component<ActionCardProps>) -> Element {} 
+```
+
+That's a lot of components for one file! We've successfully refactored our app into components, but we should probably start breaking it up into a file for each component.
+
+## Breaking into different files
+
+Fortunately, Rust has a built-in module system that's much cleaner than what you might be used to in JavaScript. Because `VoteButtons`, `TitleCard`, `MetaCard`, and `ActionCard` all belong to the `Post` component, let's put them all in a folder together called "post". We'll make a file for each component and move the props and render function.
+
+```rust
+// src/post/action.rs
+
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+struct ActionCardProps {}
+fn ActionCard((cx, props): Component<ActionCardProps>) -> Element {} 
+```
+
+We should also create a `mod.rs` file in the `post` folder so we can use it from our `main.rs`. Our `Post` component and its props will go into this file.
+
+```shell
+├── Cargo.toml
+└── src
+    ├── main.rs
+    └── post
+        ├── vote.rs
+        ├── title.rs
+        ├── meta.rs
+        ├── action.rs
+        └── mod.rs
+```
+
+
+
+In our `main.rs`, we'll want to declare the `post` module so we can access our `Post` component.
+
+```rust
+// main.rs
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App, |c| c);
+}
+
+mod post;
+
+fn App((cx, props): Component<()>) -> Element {
+    cx.render(rsx!{
+        post::Post {
+            id: Uuid::new_v4(),
+            score: 10,
+            comment_count: 10,
+            post_time: std::Instant::now(),
+            url: "example".to_string(),
+            title: "Title".to_string(),
+            original_poster: "me".to_string()
+        }
+    })
+} 
+```
+
+If you tried to build this app right now, you'll get an error message saying that `Post is private, trying changing it to public`. This is because we haven't properly exported our component! To fix this, we need to make sure both the Props and Component are declared as "public":
+
+```rust
+// src/post/mod.rs
+
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+pub struct PostProps {}
+pub fn Post((cx, props): Component<PostProps>) -> Element {} 
+```
+
+While we're here, we also need to make sure each of our subcomponents are included as modules and exported.
+
+Our "post/mod.rs" file will eventually look like this:
+
+```rust
+use dioxus::prelude::*;
+
+mod vote;
+mod title;
+mod meta;
+mod action;
+
+#[derive(Properties, PartialEq)]
+pub struct PostProps {
+    id: uuid::Uuid,
+    score: i32,
+    comment_count: u32,
+    post_time: std::time::Instant,
+    url: String,
+    title: String,
+    original_poster: String
+}
+
+pub fn Post((cx, props): Component<PostProps>) -> Element {
+    cx.render(rsx!{
+        div { class: "post-container"
+            vote::VoteButtons {
+                score: props.score,
+            }
+            title::TitleCard {
+                title: props.title,
+                url: props.url,
+            }
+            meta::MetaCard {
+                original_poster: props.original_poster,
+                post_time: props.post_time,
+            }
+            action::ActionCard {
+                post_id: props.id
+            }
+        }
+    })
+}
+```
+
+
+Ultimately, including and exporting components is governed by Rust's module system. [The Rust book is a great resource to learn about these concepts in greater detail.](https://doc.rust-lang.org/book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html)
+
+## Final structure:
+
+```shell
+├── Cargo.toml
+└── src
+    ├── main.rs
+    └── post
+        ├── vote.rs
+        ├── title.rs
+        ├── meta.rs
+        ├── action.rs
+        └── mod.rs
+```
+
+```rust
+// main.rs:
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::desktop::launch(App, |c| c);
+}
+
+mod post;
+
+fn App((cx, props): Component<()>) -> Element {
+    cx.render(rsx!{
+        post::Post {
+            id: Uuid::new_v4(),
+            score: 10,
+            comment_count: 10,
+            post_time: std::Instant::now(),
+            url: "example".to_string(),
+            title: "Title".to_string(),
+            original_poster: "me".to_string()
+        }
+    })
+} 
+```
+
+
+```rust
+// src/post/mod.rs
+use dioxus::prelude::*;
+
+mod vote;
+mod title;
+mod meta;
+mod action;
+
+#[derive(Properties, PartialEq)]
+pub struct PostProps {
+    id: uuid::Uuid,
+    score: i32,
+    comment_count: u32,
+    post_time: std::time::Instant,
+    url: String,
+    title: String,
+    original_poster: String
+}
+
+pub fn Post((cx, props): Component<PostProps>) -> Element {
+    cx.render(rsx!{
+        div { class: "post-container"
+            vote::VoteButtons {
+                score: props.score,
+            }
+            title::TitleCard {
+                title: props.title,
+                url: props.url,
+            }
+            meta::MetaCard {
+                original_poster: props.original_poster,
+                post_time: props.post_time,
+            }
+            action::ActionCard {
+                post_id: props.id
+            }
+        }
+    })
+}
+```
+
+```rust
+// src/post/vote.rs
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+pub struct VoteButtonsProps {}
+pub fn VoteButtons((cx, props): Component<VoteButtonsProps>) -> Element {} 
+```
+
+```rust
+// src/post/title.rs
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+pub struct TitleCardProps {}
+pub fn TitleCard((cx, props): Component<TitleCardProps>) -> Element {} 
+```
+
+```rust
+// src/post/meta.rs
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+pub struct MetaCardProps {}
+pub fn MetaCard((cx, props): Component<MetaCardProps>) -> Element {} 
+```
+
+```rust
+// src/post/action.rs
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+pub struct ActionCardProps {}
+pub fn ActionCard((cx, props): Component<ActionCardProps>) -> Element {} 
+```
+
+## Moving forward
+
+Next chapter, we'll start to add use code to hide and show Elements with conditional rendering.
+
+For more reading on components:
+
+- [Components in depth]()
+- [Lifecycles]()
+- [The Context object]()
+- [Optional Prop fields]()

docs/src/concepts/interactivity.md

@@ -0,0 +1 @@
+# Adding Interactivity

docs/src/concepts/lifecycles.md

@@ -0,0 +1 @@
+# Lifecycle, updates, and effects

docs/src/concepts/managing_state.md

@@ -0,0 +1 @@
+# Managing State

docs/src/concepts/old

@@ -1,32 +0,0 @@
-
-## All the VNode types
-
-VNodes can be any of:
-- **Element**: a container with a tag name, namespace, attributes, children, and event listeners
-- **Text**: bump allocated text derived from string formatting
-- **Fragments**: a container of elements with no parent
-- **Suspended**: a container for nodes that aren't yet ready to be rendered
-- **Anchor**: a special type of node that is only available when fragments have no children
-
-In practice, only elements and text can be initialized directly while other node types can only be created through hooks or NodeFactory methods.
-
-## Bump Arena Allocation
-
-To speed up the process of building our elements and text, Dioxus uses a special type of memory allocator tuned for large batches of small allocations called a Bump Arena. We use the `bumpalo` allocator which was initially developed for Dioxus' spiritual predecessor: `Dodrio.`
-
-- Bumpalo: [https://github.com/fitzgen/bumpalo](https://github.com/fitzgen/bumpalo)
-- Dodrio: [https://github.com/fitzgen/dodrio](https://github.com/fitzgen/dodrio)
-
-In other frontend frameworks for Rust, nearly every string is allocated using the global allocator. This means that strings in Rust do not benefit from the immutable string interning optimizations that JavaScript engines employ. By using a smaller, faster, more limited allocator, we can increase framework performance, bypassing even the naive WasmBindgen benchmarks for very quick renders.
-
-It's important to note that VNodes are not `'static` - the VNode definition has a lifetime attached to it:
-
-```rust, ignore
-enum VNode<'bump> {
-    VElement { tag: &'static str, children: &'bump [VNode<'bump>] },
-    VText { content: &'bump str },
-    // other VNodes ....
-}
-```
-
-Because VNodes use a bump allocator as their memory backing, they can only be created through the `NodeFactory` API - which we'll cover in the next chapter. This particular detail is important to understand because "rendering" VNodes produces a lifetime attached to the bump arena - which must be explicitly declared when dealing with components that borrow data from their parents.

docs/src/concepts/server_side_components.md

@@ -0,0 +1 @@
+# Server-side components

docs/src/concepts/suspense.md

@@ -0,0 +1 @@
+# Suspense

docs/src/concepts/vnodes.md

@@ -18,14 +18,16 @@ dioxus::ssr::render_lazy(rsx!(
     div {}
 ))
 ```
+
 Produces:
 ```html
 <div></div>
 ```
 
+We can construct any valid HTML tag with the `tag {}` pattern and expect the resulting HTML structure to resemble our declaration.
 ## Composing Elements
 
-Every element has a set of properties that can be rendered in different ways. In particular, each Element may contain other Elements. To achieve this, we can simply declare new Elements contained within the parent's curly braces:
+Of course, we need more complex structures to make our apps actually useful! Just like HTML, the `rsx!` macro lets us nest Elements inside of each other.
 
 ```rust
 #use dioxus::prelude::*;
@@ -75,11 +77,26 @@ let name = "Bob";
 rsx! ( "hello {name}" )
 ```
 
+Unfortunately, you cannot drop in arbitrary expressions directly into the string literal. In the cases where we need to compute a complex value, we'll want to use `format_args!` directly. Due to specifics of how the `rsx!` macro (we'll cover later), our call to `format_args` must be contained within curly braces *and* square braces.
+
+```rust
+rsx!( {[format_args!("Hello {}", if enabled { "Jack" } else { "Bob" } )]} )
+```
+
+This is different from React's way of generating arbitrary markup but fits within idiomatic Rust. 
+
+Typically, with Dioxus, you'll just want to compute your substrings outside of the `rsx!` call:
+
+```rust
+let name = if enabled { "Jack" } else { "Bob" };
+rsx! ( "hello {name}" )
+```
+
 ## Attributes
 
 Every Element in your User Interface will have some sort of properties that the renderer will use when drawing to the screen. These might inform the renderer if the component should be hidden, what its background color should be, or to give it a specific name or ID.
 
-To do this, we simply use the familiar struct-style syntax that Rust provides us. Commas are optional:
+To do this, we use the familiar struct-style syntax that Rust provides. Commas are optional:
 
 ```rust
 rsx!(

docs/src/depth/components.md

@@ -0,0 +1 @@
+# Components

docs/src/depth/memoization.md

@@ -0,0 +1 @@
+# Memoization

docs/src/depth/performance.md

@@ -0,0 +1 @@
+# Performance

docs/src/depth/props.md

@@ -0,0 +1 @@
+# Props

docs/src/depth/rsx.md

@@ -0,0 +1 @@
+# RSX

docs/src/depth/testing.md

@@ -0,0 +1 @@
+# Testing

docs/src/depth/topics.md

@@ -0,0 +1 @@
+# Topics in Depth

docs/src/format/README.md

@@ -1 +0,0 @@
-# Format

docs/src/format/configuration/README.md

@@ -1 +0,0 @@
-# Configuration

docs/src/format/configuration/environment-variables.md

@@ -1 +0,0 @@
-# Environment Variables

docs/src/format/configuration/general.md

@@ -1 +0,0 @@
-# General

docs/src/format/configuration/preprocessors.md

@@ -1 +0,0 @@
-# Preprocessors

docs/src/format/configuration/renderers.md

@@ -1 +0,0 @@
-# Renderers

docs/src/format/mathjax.md

@@ -1 +0,0 @@
-# MathJax Support

docs/src/format/mdbook.md

@@ -1 +0,0 @@
-# mdBook-specific features

docs/src/format/summary.md

@@ -1 +0,0 @@
-# SUMMARY.md

docs/src/format/theme/README.md

@@ -1 +0,0 @@
-# Theme

docs/src/format/theme/editor.md

@@ -1 +0,0 @@
-# Editor

docs/src/format/theme/index-hbs.md

@@ -1 +0,0 @@
-# index.hbs

docs/src/format/theme/syntax-highlighting.md

@@ -1 +0,0 @@
-# Syntax highlighting

docs/src/gettingstarted/fromjs.md

@@ -1,37 +0,0 @@
-### Immutability by default?
-
----
-
-Rust, like JS and TS, supports both mutable and immutable data. With JS, `const` would be used to signify immutable data, while in rust, the absence of `mut` signifies immutable data.
-
-Mutability:
-
-```rust
-let mut val = 10; // rust
-let val = 10;     // js
-```
-
-Immutability
-
-```rust
-let val = 10;    // rust
-const val = 10;  // js
-```
-
-However, `const` in JS does not prohibit you from modify the value itself only disallowing assignment. In Rust, immutable **is immutable**. You _never_ have to work about accidentally mutating data; mutating immutable data in Rust requires deliberate advanced datastructures that you won't find in your typical frontend code.
-
-## How do strings work?
-
----
-
-In rust, we have `&str`, `&'static str` `String`, and `Rc<str>`. It's a lot, yes, and it might be confusing at first. But it's actually not too bad.
-
-In Rust, UTF-8 is supported natively, allowing for emoji and extended character sets (like Chinese and Arabic!) instead of the typical ASCII. The primitive `str` can be seen as a couple of UTF-8 code points squished together with a dynamic size. Because this size is variable (not known at compile time for any single character), we reference an array of UTF-8 code points as `&str`. Essentially, we're referencing (the & symbol) some dynamic `str` (a collection of UTF-8 points).
-
-For text encoded directly in your code, this collection of UTF-8 code points is given the `'static` reference lifetime - essentially meaning the text can be safely referenced for the entire runtime of your program. Contrast this with JS, where a string will only exist for as long as code references it before it gets cleaned up by the garbage collector.
-
-For text that needs to have characters added, removed, sorted, uppercased, formatted, accessed for mutation, etc, Rust has the `String` type, which is essentially just a dynamically sized `str`. In JS, if you add a character to your string, you actually create an entirely new string (completely cloning the old one first). In Rust, you can safely added characters to strings _without_ having to clone first, making string manipulation in Rust very efficient.
-
-Finally, we have `Rc<str>`. This is essentially Rust's version of JavaScript's `string`. In JS, whenever you pass a `string` around (and don't mutate it), you don't actually clone it, but rather just increment a counter that says "this code is using this string." This counter prevents the garbage collector from deleting the string before your code is done using it. Only when all parts of your code are done with the string, will the string be deleted. `Rc<str>` works exactly the same way in Rust, but requires a deliberate `.clone()` to get the same behavior. In most instances, Dioxus will automatically do this for you, saving the trouble of having to `clone` when you pass an `Rc<str>` into child components. `Rc<str>` is typically better than `String` for Rust - it allows cheap sharing of strings, and through `make_mut` you can always produce your own mutable copy for modifying. You might not see `Rc<str>` in other Rust libraries as much, but you will see it in Dioxus due to Dioxus' aggressive memoization and focus on efficiency and performance.
-
-If you run into issues with `&str`, `String`, `Rc<str>`, just try cloning and `to_string` first. For the vast majority of apps, the slight performance hit will be unnoticeable. Once you get better with Strings, it's very easy to go back and remove all the clones for more efficient alternatives, but you will likely never need to.

docs/src/gettingstarted/webapps.md

@@ -1,26 +0,0 @@
-# Choose your architecture type:
-- Static Pages
-- Server-side-rendering
-- Pure SPA
-- Hybrid SPA (liveview)
-
-
-## Static Pages
-You'll want the TextRenderer crate.
-Use it imperatively by passing props and rendering to string.
-
-## Server-side-rendering
-You'll want the TextRenderer crate.
-Serve it with a dedicated middleware crate.
-
-## Pure SPA
-You'll want the WebSys Crate.
-
-## Hybrid SPA (hydration)
-You'll want the WebSys Crate
-You'll want the TextRenderer crate 
-
-
-## Hybrid SPA (liveview)
-You'll want the WebSys crate.
-You'll want the Liveview crate.

docs/src/hello_world.md

@@ -91,7 +91,7 @@ fn main() {
     dioxus::desktop::start(App, |c| c);
 }
 
-fn App(cx: Component<()>) -> Element {
+fn App((cx, props): Component<()>) -> Element {
     cx.render(rsx! (
         div { "Hello, world!" }
     ))
@@ -110,7 +110,7 @@ This bit of code imports everything from the the `prelude` module. This brings i
 use diouxs::prelude::*;
 ```
 
-This initialization code launches a Tokio runtime on a helper thread - where your code will run, and then the WebView on the main-thread. Due to platform requirements, the main thread is blocked by this call.
+This initialization code launches a Tokio runtime on a helper thread where your code will run. Then, the WebView renderer will be launched on the main-thread. Due to platform requirements, the main thread is blocked by your app's event loop.
 
 ```rust
 fn main() {
@@ -118,29 +118,37 @@ fn main() {
 }
 ```
 
-Finally, our app. Every component in Dioxus is a function that takes in `Context` and `Props` and returns an `Option<VNode>`.
+Finally, our app. Every component in Dioxus is a function that takes in `Context` and `Props` and returns an `Element`.
 
 ```rust
-fn App(cx: Component<()>) -> DomTree {
+fn App((cx, props): Component<()>) -> Element {
     cx.render(rsx! {
         div { "Hello, world!" }
     })    
 }
 ```
-
-The closure `FC<()>` syntax is identical to the function syntax, but with lifetimes managed for you. In cases where props need to borrow from their parent, you will need to specify lifetimes using the function syntax:
+In cases where props need to borrow from their parent, you will need to specify lifetimes using the function syntax:
 
 ```rust
-fn App<'a>(cx: Component<'a, ()>) -> DomTree<'a> {
+fn App<'a>(cx: Component<'a, ()>) -> Element<'a> {
     cx.render(rsx! {
         div { "Hello, world!" }
     })    
 }
 ```
 
+Writing `fn App((cx, props): Component<()>) -> Element {` might become tedious. Rust will also let you write functions as static closures, but these types of Components cannot have props that borrow data.
+```rust
+static App: Fc<()> = |(cx, props)| {
+    cx.render(rsx! {
+        div { "Hello, world!" }
+    })
+};
+```
+
 ### The `Context` object
 
-In React, you'll save data between renders with hooks. However, hooks rely on global variables which make them difficult to integrate in multi-tenant systems like server-rendering. In Dioxus, you are given an explicit `Context` object to control how the component renders and stores data.
+In React, you'll want to store data between renders with hooks. However, hooks rely on global variables which make them difficult to integrate in multi-tenant systems like server-rendering. In Dioxus, you are given an explicit `Context` object to control how the component renders and stores data.
 
 ### The `rsx!` macro
 

docs/src/platforms/00-index.md

@@ -1,16 +0,0 @@
-# Welcome to Dioxus!
-
-## Running Examples
-
-We use the dedicated `dioxus-cli` to build and test dioxus web-apps. This can run examples, tests, build web workers, launch development servers, bundle, and more. It's general purpose, but currently very tailored to Dioxus for liveview and bundling. If you've not used it before, `cargo install --path pacakages/dioxus-cli` will get it installed. This CLI tool should feel like using `cargo` but with 1st party support for assets, bundling, and other important dioxus-specific features.
-
-Alternatively, `trunk` works but can't run examples.
-
-- tide_ssr: Handle an HTTP request and return an html body using the html! macro. `cargo run --example tide_ssr`
-- doc_generator: Use dioxus SSR to generate the website and docs. `cargo run --example doc_generator`
-- fc_macro: Use the functional component macro to build terse components. `cargo run --example fc_macro`
-- hello_web: Start a simple wasm app. Requires a web packer like dioxus-cli or trunk `cargo run --example hello`
-- router: `cargo run --example router`
-- tide_ssr: `cargo run --example tide_ssr`
-- webview: Use liveview to bridge into a webview context for a simple desktop application. `cargo run --example webview`
-- twitter-clone: A full-featured Twitter clone showcasing dioxus-liveview, state management patterns, and hooks. `cargo run --example twitter`

docs/src/platforms/01-ssr.md

@@ -1,3 +0,0 @@
-# The Server-Side-Rendering Guide
-
-This guide will help you build your first app that leverages server-side-rendering to display the user interface.

docs/src/platforms/02-wasm.md

@@ -1,3 +0,0 @@
-# The WASM Guide
-
-This guide will help you build your first app that leverages WASM in the browser to display the user interface.

docs/src/platforms/03-desktop.md

@@ -1,3 +0,0 @@
-# The Desktop Guide
-
-This guide will help you build your first app that leverages webview for desktop to display the user interface.

docs/src/platforms/04-concurrency.md

@@ -1,21 +0,0 @@
-## Concurrency
-
-In Dioxus, VNodes are asynchronous and can their rendering can be paused at any time by awaiting a future. Hooks can combine this functionality with the Context and Subscription APIs to craft dynamic and efficient user experiences.
-
-```rust
-fn user_data(cx: Context<()>) -> DomTree {
-    // Register this future as a task
-    use_suspense(cx, async {
-        // Continue on with the component as usual, waiting for data to arrive
-        let Profile { name, birthday, .. } = fetch_data().await;
-        html! {
-            <div>
-                {"Hello, {name}!"}
-                {if birthday === std::Instant::now() {html! {"Happy birthday!"}}}
-            </div>
-        }
-    })
-}
-```
-
-Asynchronous components are powerful but can also be easy to misuse as they pause rendering for the component and its children. Refer to the concurrent guide for information on how to best use async components.

docs/src/platforms/05-liveview.md

@@ -1,20 +0,0 @@
-## Liveview
-
-With the Context, Subscription, and Asynchronous APIs, we've built Dioxus Liveview: a coupling of frontend and backend to deliver user experiences that do not require dedicated API development. Instead of building and maintaining frontend-specific API endpoints, components can directly access databases, server caches, and other services directly from the component.
-
-These set of features are still experimental. Currently, we're still working on making these components more ergonomic
-
-```rust
-fn live_component(cx: &Context<()>) -> DomTree {
-    use_live_component(
-        cx,
-        // Rendered via the client
-        #[cfg(target_arch = "wasm32")]
-        || html! { <div> {"Loading data from server..."} </div> },
-
-        // Renderered on the server
-        #[cfg(not(target_arch = "wasm32"))]
-        || html! { <div> {"Server Data Loaded!"} </div> },
-    )
-}
-```

docs/src/platforms/06-components.md

@@ -1,31 +0,0 @@
-## Components
-
-Dioxus should look and feel just like writing functional React components. In Dioxus, there are no class components with lifecycles. All state management is done via hooks. This encourages logic reusability and lessens the burden on Dioxus to maintain a non-breaking lifecycle API.
-
-```rust
-#[derive(Properties, PartialEq)]
-struct MyProps {
-    name: String
-}
-
-fn Example(cx: Context<MyProps>) -> DomTree {
-    html! { <div> "Hello {cx.cx.name}!" </div> }
-}
-```
-
-Here, the `Context` object is used to access hook state, create subscriptions, and interact with the built-in context API. Props, children, and component APIs are accessible via the `Context` object. The functional component macro makes life more productive by inlining props directly as function arguments, similar to how Rocket parses URIs.
-
-```rust
-// A very terse component!
-#[fc]
-fn Example(cx: Context, name: String) -> DomTree {
-    html! { <div> "Hello {name}!" </div> }
-}
-
-// or
-
-#[functional_component]
-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.

docs/src/setup.md

@@ -2,7 +2,7 @@
 
 Dioxus aims to provide a fast, friendly, and portable toolkit for building user interfaces with Rust.
 
-This Getting Setup guide assumes you'll be building a small desktop application. The process for building web-apps, desktop apps, server-rendered apps, static sites, and mobile apps, is more-or-less the same. You can check out the [Platform Specific Guides](../platforms/00-index.md) for more information on setting up Dioxus for any of the various targets you are building for.
+This Getting Setup guide assumes you'll be building a small desktop application. You can check out the [Platform Specific Guides](../platforms/00-index.md) for more information on setting up Dioxus for any of the various supported platforms.
 
 # Setting up Dioxus
 
@@ -16,7 +16,7 @@ Dioxus integrates very well with the Rust-Analyzer IDE plugin which will provide
 
 ### Dioxus-CLI for dev server, bundling, etc.
 
-We also recommend installing the Dioxus CLI. The Dioxus CLI automates building and packaging for various targets and integrates with simulators, development servers, and app deployment. It'll be our one-stop-shop for anything related to building and sharing our Dioxus Apps. To install the CLI, you'll need cargo (should be automatically installed with Rust):
+We also recommend installing the Dioxus CLI. The Dioxus CLI automates building and packaging for various targets and integrates with simulators, development servers, and app deployment. To install the CLI, you'll need cargo (should be automatically installed with Rust):
 
 ```
 $ cargo install dioxus-cli

docs/src/tutorial/advanced_guides.md

@@ -0,0 +1 @@
+# Advanced Guides

docs/src/tutorial/components.md

@@ -0,0 +1 @@
+# Defining Components

docs/src/tutorial/index.md

@@ -0,0 +1,13 @@
+# Putting it all together
+
+So far, we've covered the basics of Dioxus. We've talked about:
+
+- Elements
+- Components
+- Interactivity
+- State Management
+- Async Actions
+- Styling
+
+In this chapter, we'll build a real-world weather app that combines everything we've learned into a cute application that you can run locally. It'll let us monitor different locations simultaneously and periodically check for updates.
+

docs/src/tutorial/new_app.md

@@ -0,0 +1 @@
+# New app

docs/src/tutorial/publishing.md

@@ -0,0 +1 @@
+# Publishing

docs/src/tutorial/state.md

@@ -0,0 +1 @@
+# Defining State

docs/src/tutorial/structure.md

@@ -0,0 +1 @@
+# Structuring our app

docs/src/tutorial/styling.md

@@ -0,0 +1 @@
+# Styling

src/lib.rs

@@ -193,7 +193,7 @@ pub mod debug {}
 pub mod prelude {
     //! A glob import that includes helper types like FC, rsx!, html!, and required traits
     pub use dioxus_core::prelude::*;
-    pub use dioxus_core_macro::{format_args_f, html, rsx, Props};
+    pub use dioxus_core_macro::{format_args_f, rsx, Props};
     pub use dioxus_elements::{GlobalAttributes, SvgAttributes};
     pub use dioxus_hooks::*;
     pub use dioxus_html as dioxus_elements;