Merge pull request #106 from DioxusLabs/jk/docs

docs: improve components and elements

.vscode/spellright.dict

@@ -69,3 +69,13 @@ Jank
 noderef
 reborrow
 VirtualDoms
+bootstrapper
+WebkitGtk
+laymans
+iter
+cloneable
+fudamental
+clonable
+oninput
+Webview
+idanarye

docs/guide/src/ROADMAP.md

@@ -0,0 +1,114 @@
+# Roadmap & Feature-set
+
+Before we dive into Dioxus, feel free to take a look at our feature set and roadmap to see if what Dioxus can do today works for you.
+
+If a feature that you need doesn't exist or you want to contribute to projects on the roadmap, feel free to get involved by [joining the discord](https://discord.gg/XgGxMSkvUM).
+
+Generally, here's the status of each platform:
+
+- **Web**: Dioxus is a great choice for pure web-apps - especially for CRUD/complex apps. However, it does lack the ecosystem of React, so you might be missing a component library or some useful hook.
+
+- **SSR**: Dioxus is a great choice for pre-rendering, hydration, and rendering HTML on a web endpoint. Be warned - the VirtualDom is not (currently) `Send + Sync`.
+
+- **Desktop**: You can build very competent single-window desktop apps right now. However, multi-window apps require support from Dioxus core and are not ready.
+
+- **Mobile**: Mobile support is very young. You'll be figuring things out as you go and there are not many support crates for peripherals.
+
+- **LiveView**: LiveView support is very young. You'll be figuring things out as you go. Thankfully, none of it is too hard and any work can be upstreamed into Dioxus.
+
+## Features
+---
+
+| Feature                   | Status | Description                                                          |
+| ------------------------- | ------ | -------------------------------------------------------------------- |
+| Conditional Rendering     | ✅      | if/then to hide/show component                                       |
+| Map, Iterator             | ✅      | map/filter/reduce to produce rsx!                                    |
+| Keyed Components          | ✅      | advanced diffing with keys                                           |
+| Web                       | ✅      | renderer for web browser                                             |
+| Desktop (webview)         | ✅      | renderer for desktop                                                 |
+| Shared State (Context)    | ✅      | share state through the tree                                         |
+| Hooks                     | ✅      | memory cells in components                                           |
+| SSR                       | ✅      | render directly to string                                            |
+| Component Children        | ✅      | cx.children() as a list of nodes                                     |
+| Headless components       | ✅      | components that don't return real elements                           |
+| Fragments                 | ✅      | multiple elements without a real root                                |
+| Manual Props              | ✅      | Manually pass in props with spread syntax                            |
+| Controlled Inputs         | ✅      | stateful wrappers around inputs                                      |
+| CSS/Inline Styles         | ✅      | syntax for inline styles/attribute groups                            |
+| Custom elements           | ✅      | Define new element primitives                                        |
+| Suspense                  | ✅      | schedule future render from future/promise                           |
+| Integrated error handling | ✅      | Gracefully handle errors with ? syntax                               |
+| NodeRef                   | ✅      | gain direct access to nodes                                          |
+| Re-hydration              | ✅      | Pre-render to HTML to speed up first contentful paint                |
+| Jank-Free Rendering       | ✅      | Large diffs are segmented across frames for silky-smooth transitions |
+| Effects                   | ✅      | Run effects after a component has been committed to render           |
+| Portals                   | 🛠      | Render nodes outside of the traditional tree structure               |
+| Cooperative Scheduling    | 🛠      | Prioritize important events over non-important events                |
+| Server Components         | 🛠      | Hybrid components for SPA and Server                                 |
+| Bundle Splitting          | 👀      | Efficiently and asynchronously load the app                          |
+| Lazy Components           | 👀      | Dynamically load the new components as the page is loaded            |
+| 1st class global state    | ✅      | redux/recoil/mobx on top of context                                  |
+| Runs natively             | ✅      | runs as a portable binary w/o a runtime (Node)                       |
+| Subtree Memoization       | ✅      | skip diffing static element subtrees                                 |
+| High-efficiency templates | 🛠      | rsx! calls are translated to templates on the DOM's side             |
+| Compile-time correct      | ✅      | Throw errors on invalid template layouts                             |
+| Heuristic Engine          | ✅      | track component memory usage to minimize future allocations          |
+| Fine-grained reactivity   | 👀      | Skip diffing for fine-grain updates                                  |
+
+- ✅ = implemented and working
+- 🛠 = actively being worked on
+- 👀 = not yet implemented or being worked on
+- ❓ = not sure if will or can implement
+
+
+## Roadmap
+---
+
+
+Core:
+- [x] Release of Dioxus Core
+- [x] Upgrade documentation to include more theory and be more comprehensive
+- [ ] Support for HTML-side templates for lightning-fast dom manipulation
+- [ ] Support for multiple renderers for same virtualdom (subtrees)
+- [ ] Support for ThreadSafe (Send + Sync)
+- [ ] Support for Portals
+
+SSR
+- [x] SSR Support + Hydration
+- [ ] Integrated suspense support for SSR
+
+Desktop
+- [ ] Declarative window management
+- [ ] Templates for building/bundling
+- [ ] Fully native renderer
+- [ ] Access to Canvas/WebGL context natively
+
+Mobile
+- [ ] Mobile standard library 
+  - [ ] GPS
+  - [ ] Camera
+  - [ ] filesystem
+  - [ ] Biometrics
+  - [ ] WiFi
+  - [ ] Bluetooth
+  - [ ] Notifications
+  - [ ] Clipboard
+  - [ ] 
+
+Bundling (CLI)
+- [x] translation from HTML into RSX
+- [ ] dev server
+- [ ] live reload
+- [ ] translation from JSX into RSX
+- [ ] hot module replacement
+- [ ] code splitting
+- [ ] asset macros
+- [ ] css pipeline
+- [ ] image pipeline
+
+Essential hooks
+- [ ] Router
+- [ ] Global state management
+- [ ] Resize observer
+
+

docs/guide/src/SUMMARY.md

@@ -1,19 +1,28 @@
 # Summary
 
 - [Introduction](README.md)
+- [Roadmap](ROADMAP.md)
 - [Getting Set Up](setup.md)
 - [Hello, World!](hello_world.md)
 - [Describing the UI](elements/index.md)
   - [Intro to Elements](elements/vnodes.md)
-  - [Intro to Components](elements/components.md)
-  - [The Props Macro](elements/propsmacro.md)
-  - [Reusing, Importing, and Exporting Components](elements/exporting_components.md)
-  - [Passing children and attributes](elements/component_children.md)
   - [Conditional Rendering](elements/conditional_rendering.md)
   - [Lists](elements/lists.md)
+  - [Special Attributes](elements/special_attributes.md)
+- [Components](elements/components.md)
+  - [Properties](elements/propsmacro.md)
+  - [Reusing, Importing, and Exporting](elements/exporting_components.md)
+  - [Children and Attributes](elements/component_children.md)
+  - [How Data Flows](elements/composing.md)
+- [Thinking Reactively]()
+  - [Thinking Reactively]()
+  - [Thinking Reactively]()
+  - [Thinking Reactively]()
+  - [Thinking Reactively]()
 - [Adding Interactivity](interactivity/index.md)
   - [Hooks and Internal State](interactivity/hooks.md)
-  - [Event handlers](interactivity/event_handlers.md)
+  - [UseState and UseRef](interactivity/importanthooks.md) 
+  - [Event Listeners](interactivity/event_handlers.md)
   - [User Input and Controlled Components](interactivity/user_input.md)
   - [Lifecycle, updates, and effects](interactivity/lifecycles.md)
 - [Managing State](state/index.md)
@@ -41,3 +50,4 @@
 
   <!-- - [Suspense](concepts/suspense.md) -->
   <!-- - [Async Callbacks](concepts/asynccallbacks.md) -->
+

docs/guide/src/async/fetching.md

@@ -1 +1,4 @@
 # Fetching
+
+
+This section is currently under construction! 🏗

docs/guide/src/async/index.md

@@ -17,3 +17,6 @@ Writing apps that deal with Send/Sync can be frustrating at times. Under the hoo
 
 
 All async code in your app is polled on a `LocalSet`, so any async code we w
+
+
+> This section is currently under construction! 🏗

docs/guide/src/elements/component_children.md

@@ -137,7 +137,7 @@ fn clickable(cx: Scope<ClickableProps>) -> Element {
 }
 ```
 
-## Passing attributes
+<!-- ## Passing attributes
 
 In the cases where you need to pass arbitrary element properties into a component - say to add more functionality to the `<a>` tag, Dioxus will accept any quoted fields. This is similar to adding arbitrary fields to regular elements using quotes.
 
@@ -171,7 +171,7 @@ fn clickable(cx: Scope<ClickableProps>) -> Element {
 ```
 
 The quoted escapes are a great way to make your components more flexible.
-
+ -->
 
 ## Passing handlers
 

docs/guide/src/elements/components.md

@@ -106,7 +106,7 @@ fn Post(cx: Scope<PostProps>) -> Element {
 }
 ```
 
-When declaring a component in `rsx!`, we can pass in properties using the traditional Rust struct syntax. Dioxus will automatically call "into" on the property fields, cloning when necessary. Our `Post` component is simply a collection of smaller components wrapped together in a single container.
+When declaring a component in `rsx!`, we can pass in properties using the traditional Rust struct syntax. Our `Post` component is simply a collection of smaller components wrapped together in a single container.
 
 Let's take a look at the `VoteButton` component. For now, we won't include any interactivity - just the rendering the score and buttons to the screen.
 

docs/guide/src/elements/composing.md

@@ -0,0 +1,243 @@
+# Thinking in React
+
+We've finally reached the point in our tutorial where we can talk about the "Theory of React." We've talked about defining a declarative view, but not about the aspects that make our code *reactive*.
+
+Understanding the theory of reactive programming is essential to making sense of Dioxus and writing effective, performant UIs.
+
+In this section, we'll talk about:
+
+- One-way data flow
+- Modifying data
+- Forcing renders
+- How renders propagate
+
+This section is a bit long, but worth the read. We recommend coffee, tea, and/or snacks.
+
+## Reactive Programming
+
+Dioxus is one the very few Rust libraries that provide a "Reactive Programming Model". The term "Reactive programming" is a classification of programming paradigm - much like functional or imperative programming. This is a very important distinction since it affects how we *think* about our code.
+
+Reactive programming is a programming model concerned with deriving computations from asynchronous data flow. Most reactive programs are comprised of datasources, intermediate computations, and a final result.
+
+We consider the rendered GUI to be the final result of our Dioxus apps. The datasources for our apps include local and global state.
+
+For example, the model presented in the figure below is comprised of two data sources: time and a constant. These values are passed through our computation graph to achieve a final result: `g`.
+
+![Reactive Model](https://upload.wikimedia.org/wikipedia/commons/thumb/e/e9/Reactive_programming_glitches.svg/440px-Reactive_programming_glitches.svg.png)
+
+Whenever our `seconds` variable changes, we will then reevaluate the computation for `t`. Because `g` relies on `t`, we will also reevaluate its computation too. Notice that we would've reevaluated the computation for `g` even if `t` didn't change because `seconds` is used to calculate `g`.
+
+However, if we somehow changed our constant from `1` to `2`, then we need to reevaluate `t`. If, for whatever reason, this change did not affect the result of `t`, then we wouldn't try to reevaluate `g`.
+
+In Reactive Programming, we don't think about whether or not we should reevaluate `t` or `g`; instead, we simply provide functions of computation and let the framework figure out the rest for us.
+
+In Rust, our reactive app would look something like:
+
+```rust
+fn compute_g(t: i32, seconds: i32) -> bool {
+    t > seconds
+}
+
+fn compute_t(constant: i32, seconds: i32) -> i32 {
+    constant + seconds
+}
+
+fn compute_graph(constant: i32, seconds: i32) -> bool {
+    let t = compute_t(constant, seconds);
+    let g = compute_g(t, seconds);
+    g
+}
+```
+
+## How is Dioxus Reactive?
+
+The Dioxus VirtualDom provides us a framework for reactive programming. When we build apps with dioxus, we need to provide our own datasources. This can be either initial props or some values fetched from the network. We then pass this data through our app into components through properties. 
+
+If we represented the reactive graph presented above in Dioxus, it would look very similar:
+
+```rust
+// Declare a component that holds our datasources and calculates `g`
+fn RenderGraph(cx: Scope) -> Element {
+    let seconds = use_datasource(SECONDS);
+    let constant = use_state(&cx, || 1);
+
+    cx.render(rsx!( 
+        RenderG { seconds: seconds } 
+        RenderT { seconds: seconds, constant: constant }
+    ))
+}
+
+// "calculate" g by rendering `t` and `seconds`
+#[inline_props]
+fn RenderG(cx: Scope, seconds: i32) -> Element {
+    cx.render(rsx!{ "There are {seconds} seconds remaining..." })
+}
+
+// calculate and render `t` in its own component
+#[inline_props]
+fn RenderT(cx: Scope, seconds: i32, constant: i32) -> Element {
+    let res = seconds + constant;
+    cx.render(rsx!{ "{res}" })
+}
+```
+
+With this app, we've defined three components. Our top-level component provides our datasources (the hooks), computation nodes (child components), and a final value (what's "rendered").
+
+Now, whenever the `constant` changes, our `RenderT` component will be re-rendered. However, if `seconds` doesn't change, then we don't need to re-render `RenderG` because the input is the same. If `seconds` *does* change, then both RenderG and RenderT will be reevaluated.
+
+Dioxus is "Reactive" because it provides this framework for us. All we need to do is write our own tiny units of computation and Dioxus figures out which components need to be reevaluated automatically.
+
+These extra checks and algorithms add some overhead, which is why you see projects like [Sycamore](http://sycamore-rs.netlify.app) and [SolidJS](http://solidjs.com) eliminating them altogether. Dioxus is *really* fast, so we're willing to exchange the added overhead for improved developer experience.
+
+## How do we update values in our dataflow graph?
+
+Dioxus will automatically figure out how to regenerate parts of our app when datasources change. But how exactly can we update our data sources?
+
+In Dioxus there are two datasources:
+
+1. Local state in `use_hook` and all other hooks
+2. Global state through `provide_context`.
+
+Technically, the root props of the VirtualDom are a third datasource, but since we cannot modify them, they are not worth talking about.
+
+### Local State
+
+For local state in hooks, Dioxus gives us the `use_hook` method which returns an `&mut T` without any requirements. This means raw hook values are not tracked by Dioxus. In fact, we could write a component that modifies a hook value directly:
+
+```rust
+fn app(cx: Scope) -> Element {
+    let mut count = cx.use_hook(|_| 0);
+    cx.render(rsx!{
+        button { 
+            onclick: move |_| *count += 1, 
+            "Count: {count}"
+        }
+    })
+}
+```
+
+However, when this value is written to, the component does not know to be reevaluated. We must explicitly tell Dioxus that this component is "dirty" and needs to be re-rendered. This is done through the `cx.needs_update` method:
+
+```rust
+button { 
+    onclick: move |_| {
+        *count += 1;
+        cx.needs_update();
+    }, 
+    "Count: {count}"
+}
+```
+
+Now, whenever we click the button, the value will change and the component will be re-rendered.
+
+> Re-rendering is when Dioxus calls your function component *again*. Component functions will be called over and over throughout their lifetime, so they should be mostly side-effect free.
+
+### Understand this!
+
+Your component functions will be called ("rendered" in our lingo) for as long as the component is present in the tree.
+
+A single component will be called multiple times, modifying its own internal state or rendering new nodes with new values from its properties.
+
+### App-Global State
+
+With the `provide_context` and `consume_context` methods on `Scope`, we can share values to descendants without having to pass values through component props. This has the side-effect of making our datasources less obvious from a high-level perspective, but it makes our components more modular within the same codebase.
+
+To make app-global state easier to reason about, Dioxus makes all values provided through `provide_context` immutable. This means any library built on top of `provide_context` needs to use interior mutability to modify shared global state.
+
+In these cases, App-Global state needs to manually track which components need to be re-generated. 
+
+To regenerate *any* component in your app, you can get a handle to the Dioxus' internal scheduler through `schedule_update_any`:
+
+```rust
+let force_render = cx.schedule_update_any();
+
+// force a render of the root component
+force_render(ScopeId(0));
+```
+
+## What does it mean for a component to "re-render"?
+
+In our guides, we frequently use the phrase "re-render" to describe updates to our app. You'll often hear this paired with "preventing unnecessary re-renders." But what exactly does this mean?
+
+When we call `dioxus::desktop::launch`, Dioxus will create a new `Scope` object and call the component we gave it. Our `rsx!` calls will create new nodes which we return back to the VirtualDom. Dioxus will then look through these nodes for child components, call their functions, and so on until every component has been "rendered." We consider these nodes "rendered" because they were created because of our explicit actions.
+
+The tree of UI that dioxus creates will roughly look like the tree of components presented earlier:
+
+![Tree of UI](../images/component_tree.png)
+
+But what happens when we call `needs_update` after modifying some important state? Well, if Dioxus called our component's function again, then we would produce new, different nodes. In fact, this is exactly what Dioxus does! 
+
+At this point, we have some old nodes and some new nodes. Again, we call this "rendering" because Dioxus had to create new nodes because of our explicit actions. Any time new nodes get created, our VirtualDom is being "rendered."
+
+These nodes are stored in an extremely efficient memory allocator called a "bump arena." For example, a div with a handler and attribute would be stored in memory in two locations: the "old" tree and the "new" tree.
+
+![Bump Arenas](../images/oldnew.png)
+
+From here, Dioxus computes the difference between these trees and updates the Real DOM to make it look like the new version of what we've declared.
+
+![Diffing](../images/diffing.png)
+
+## Suppressing Renders
+
+So, we know how to make Dioxus render, but how do we *stop* it? What if we *know* that our state didn't change and we shouldn't render and diff new nodes because they'll be exactly the same as the last time?
+
+In these cases, you want to reach for *memoization*. In Dioxus, memoization involves preventing a component from rendering again if its props didn't change since the last time it attempted to render.
+
+Visually, you can tell that a component will only re-render if the new value is sufficiently different than the old one.
+
+| props.val | re-render |
+| --------- | --------- |
+| 10        | true      |
+| 20        | true      |
+| 20        | false     |
+| 20        | false     |
+| 10        | true      |
+| 30        | false     |
+
+This is why when you `derive(Props)`, you must also implement the `PartialEq` trait. To override the memoization strategy for a component, you can simply implement your own PartialEq.
+
+```rust
+struct CustomProps {
+    val: i32,
+}
+
+impl PartialEq for CustomProps {
+    fn partial_eq(&self, other: &Self) -> bool {
+        // we don't render components that have a val less than 5
+        if other.val > 5 && self.val > 5{
+            self.val == other.val
+        }
+    }
+}
+```
+
+However, for components that borrow data, it doesn't make sense to implement PartialEq since the actual references in memory might be different.
+
+You can technically override this behavior by implementing the `Props` trait manually, though it's unsafe and easy to mess up:
+
+```rust
+impl Properties for CustomProps {
+    fn memoize(&self, other &Self) -> bool {
+        self != other
+    }
+}
+```
+
+TLDR:
+- Dioxus checks if props changed between renders
+- If props changed according to PartialEq, Dioxus re-renders the component
+- Props that have a lifetime (ie `<'a>`) will always be re-rendered
+
+## Wrapping Up
+
+Wow, that was a lot of material!
+
+Let's see if we can recap what was presented:
+
+- Reactive programming calculates a final value from datasources and computation
+- Dioxus is "reactive" since it figures out which computations to check
+- `schedule_update` must be called to mark a component as dirty
+- dirty components will be re-rendered (called multiple times) to produce a new UI
+- Renders can be suppressed with memoization
+
+This theory is crucial to understand how to compose components and how to control renders in your app.

docs/guide/src/elements/exporting_components.md

@@ -66,6 +66,14 @@ fn ActionCard(Scope<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.
 
+```rust
+use dioxus::prelude::*;
+
+#[derive(PartialEq, Props)]
+struct PostProps {}
+fn Post(Scope<PostProps>) -> Element {}
+```
+
 ```shell
 ├── Cargo.toml
 └── src
@@ -78,8 +86,6 @@ We should also create a `mod.rs` file in the `post` folder so we can use it from
         └── mod.rs
 ```
 
-
-
 In our `main.rs`, we'll want to declare the `post` module so we can access our `Post` component.
 
 ```rust
@@ -164,7 +170,6 @@ pub fn Post(Scope<PostProps>) -> Element {
 }
 ```
 
-
 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:

docs/guide/src/elements/lists.md

@@ -10,14 +10,24 @@ In this chapter, you will learn:
 
 ## Rendering data from lists
 
-Thinking back to our analysis of the `r/reddit` page, we notice a list of data that needs to be rendered: the list of posts. This list of posts is always changing, so we cannot just hardcode the lists into our app like:
+If we wanted to build the Reddit app, then we need to implement a list of data that needs to be rendered: the list of posts. This list of posts is always changing, so we cannot just hardcode the lists into our app directly, like so:
 
 ```rust
+// we shouldn't ship our app with posts that don't update!
 rsx!(
     div {
-        Post {/* some properties */}
-        Post {/* some properties */}
-        Post {/* some properties */}
+        Post {
+            title: "Post A",
+            votes: 120,
+        }
+        Post {
+            title: "Post B",
+            votes: 14,
+        }
+        Post {
+            title: "Post C",
+            votes: 999,
+        }
     }
 )
 ```
@@ -45,10 +55,21 @@ Finally, we can include this list in the final structure:
 ```rust
 rsx!(
     ul {
-        {name_list}
+        name_list
     }
 )
 ```
+Or, we can include the iterator inline:
+```rust
+rsx!(
+    ul {
+        names.iter().map(|name| rsx!(
+            li { "{name}" } 
+        ))
+    }
+)
+```
+
 The HTML-rendered version of this list would follow what you would expect:
 ```html
 <ul>
@@ -157,7 +178,7 @@ File names in a folder and Element keys in an array serve a similar purpose. The
 ### Gotcha
 You might be tempted to use an item’s index in the array as its key. In fact, that’s what Dioxus will use if you don’t specify a key at all. But the order in which you render items will change over time if an item is inserted, deleted, or if the array gets reordered. Index as a key often leads to subtle and confusing bugs.
 
-Similarly, do not generate keys on the fly, `gen_random`. This will cause keys to never match up between renders, leading to all your components and DOM being recreated every time. Not only is this slow, but it will also lose any user input inside the list items. Instead, use a stable ID based on the data.
+Similarly, do not generate keys on the fly, like `gen_random`. This will cause keys to never match up between renders, leading to all your components and DOM being recreated every time. Not only is this slow, but it will also lose any user input inside the list items. Instead, use a stable ID based on the data.
 
 Note that your components won’t receive key as a prop. It’s only used as a hint by Dioxus itself. If your component needs an ID, you have to pass it as a separate prop:
 ```rust

docs/guide/src/elements/propsmacro.md

@@ -1 +1,192 @@
-# The Props Macro
+# Component Properties
+
+All component `properties` must implement the `Properties` trait. The `Props` macro automatically derives this trait but adds some additional functionality. In this section, we'll learn about:
+
+- Using the props macro
+- Memoization through PartialEq
+- Optional fields on props
+- The inline_props macro    
+
+
+
+## Using the Props Macro
+
+All `properties` that your components take must implement the `Properties` trait. The simplest props you can use is simply `()` - or no value at all. `Scope` is generic over your component's props and actually defaults to `()`.
+
+```rust
+// this scope
+Scope<()> 
+
+// is the same as this scope
+Scope
+```
+
+If we wanted to define a component with its own props, we would create a new struct and tack on the `Props` derive macro:
+
+```rust
+#[derive(Props)]
+struct MyProps {
+    name: String
+}
+```
+This particular code will not compile - all `Props` must either a) borrow from their parent or b) implement `PartialEq`. Since our props do not borrow from their parent, they are `'static` and must implement PartialEq.
+
+For an owned example:
+```rust
+#[derive(Props, PartialEq)]
+struct MyProps {
+    name: String
+}
+```
+
+For a borrowed example:
+```rust
+#[derive(Props)]
+struct MyProps<'a> {
+    name: &'a str
+}
+```
+
+Then, to use these props in our component, we simply swap out the generic parameter on scope.
+
+For owned props, we just drop it in:
+
+```rust
+fn Demo(cx: Scope<MyProps>) -> Element {
+    todo!()
+}
+```
+
+However, for props that borrow data, we need to explicitly declare lifetimes. Rust does not know that our props and our component share the same lifetime, so must explicitly attach a lifetime in two places:
+
+```rust
+fn Demo<'a>(cx: Scope<'a, MyProps<'a>>) -> Element {
+    todo!()
+}
+```
+
+By putting the `'a` lifetime on Scope and our Props, we can now borrow data from our parent and pass it on to our children.
+
+
+## Memoization
+
+If you're coming from React, you might be wondering how memoization fits in. For our purpose, memoization is the process in which we check if a component actually needs to be re-rendered when its props change. If a component's properties change but they wouldn't necessarily affect the output, then we don't need to actually re-render the component.
+
+For example, let's say we have a component that has two children:
+
+```rust
+fn Demo(cx: Scope) -> Element {
+    let name = use_state(&cx, || String::from("bob"));
+    let age = use_state(&cx, || 21);
+
+    cx.render(rsx!{
+        Name { name: name }
+        Age { age: age }
+    })
+}
+```
+
+If `name` changes but `age` does not, then there is no reason to re-render our `Age` component since the contents of its props did not meaningfully change.
+
+
+Dioxus implements memoization by default, which means you can always rely on props with `PartialEq` or no props at all to act as barriers in your app. This can be extremely useful when building larger apps where properties frequently change. By moving our state into a global state management solution, we can achieve precise, surgical re-renders, improving the performance of our app.
+
+
+However, for components that borrow values from their parents, we cannot safely memoize them.
+
+For example, this component borrows `&str` - and if the parent re-renders, then the actual reference to `str` will probably be different. Since the data is borrowed, we need to pass a new version down the tree.
+
+```rust
+#[derive(Props)]
+struct MyProps<'a> {
+    name: &'a str
+}
+
+fn Demo<'a>(cx: Scope<'a, MyProps<'a>>) -> Element {
+    todo!()
+}
+```
+
+TLDR: 
+- if you see props with a lifetime or generics, it cannot be memoized
+- memoization is done automatically through the `PartialEq` trait
+- components with empty props can act as memoization barriers
+
+## Optional Fields
+
+Dioxus' `Props` macro is very similar to [@idanarye](https://github.com/idanarye)'s [TypedBuilder crate](https://github.com/idanarye/rust-typed-builder) and supports many of the same parameters.
+
+For example, you can easily create optional fields by attaching the `optional` modifier to a field.
+
+```rust
+#[derive(Props, PartialEq)]
+struct MyProps {
+    name: String,
+
+    #[props(optional)]
+    description: Option<String>
+}
+
+fn Demo(cx: MyProps) -> Element {
+    ...
+}
+```
+
+Then, we can completely omit the description field when calling the component:
+
+```rust
+rsx!{
+    Demo {
+        name: "Thing".to_string(),
+        // description is omitted
+    }
+}
+```
+
+The `optional` modifier is a combination of two separate modifiers: `default` and `strip_option`. The full list of modifiers includes:
+
+- `default` - automatically add the field using its `Default` implementation
+- `strip_option` - automatically wrap values at the call site in `Some`
+- `optional` - combine both `default` and `strip_option`
+- `into` - automatically call `into` on the value at the callsite
+
+For more information on how tags work, check out the [TypedBuilder](https://github.com/idanarye/rust-typed-builder) crate. However, all attributes for props in Dioxus are flattened (no need for `setter` syntax) and the `optional` field is new.
+
+
+
+
+## The inline_props macro
+
+Yes - *another* macro! However, this one is entirely optional.
+
+For internal components, we provide the `inline_props` macro, which will let you embed your `Props` definition right into the function arguments of your component.
+
+Our title card above would be transformed from:
+
+```rust
+#[derive(Props, PartialEq)]
+struct TitleCardProps {
+    title: String,
+}
+
+fn TitleCard(cx: Scope<TitleCardProps>) -> Element {
+    cx.render(rsx!{
+        h1 { "{cx.props.title}" }
+    })
+}   
+```
+
+to:
+
+```rust
+#[inline_props]
+fn TitleCard(cx: Scope, title: String) -> Element {
+    cx.render(rsx!{
+        h1 { "{title}" }
+    })
+}   
+```
+
+Again, this macro is optional and should not be used by library authors since you have less fine-grained control over documentation and optionality.
+
+However, it's great for quickly throwing together an app without dealing with *any* extra boilerplate.

docs/guide/src/elements/special_attributes.md

@@ -0,0 +1,192 @@
+# Special Attributes
+
+Dioxus tries its hardest to stay close to React, but there are some divergences and "special behavior" that you should review before moving on.
+
+In this section, we'll cover special attributes built into Dioxus:
+
+- `dangerous_inner_html`
+- Boolean attributes
+- `prevent_default`
+<!-- - `..Attributes` -->
+- event handlers as string attributes
+- `value`, `checked`, and `selected`
+
+## The HTML escape hatch: `dangerous_inner_html`
+
+One thing you might've missed from React is the ability to render raw HTML directly to the DOM. If you're working with pre-rendered assets, output from templates, or output from a JS library, then you might want to pass HTML directly instead of going through Dioxus. In these instances, reach for `dangerous_inner_html`.
+
+For example, shipping a markdown-to-Dioxus converter might significantly bloat your final application size. Instead, you'll want to pre-render your markdown to HTML and then include the HTML directly in your output. We use this approach for the `http://dioxuslabs.com` site:
+
+
+```rust
+fn BlogPost(cx: Scope) -> Element {
+    let contents = include_str!("../post.html");
+    cx.render(rsx!{
+        div {
+            class: "markdown",
+            dangerous_inner_html: "{contents}",
+        }
+    })
+}
+```
+
+> Note! This attribute is called "dangerous_inner_html" because it is DANGEROUS. If you're not careful, you can easily expose cross-site-scripting (XSS) attacks to your users. If you're handling untrusted input, make sure to escape your HTML before passing it into `dangerous_inner_html`.
+
+
+## Boolean Attributes
+
+Most attributes, when rendered, will be rendered exactly as the input you provided. However, some attributes are considered "boolean" attributes and just their presence determines whether or not they affect the output. For these attributes, a provided value of `"false"` will cause them to be removed from the target element.
+
+So the input of:
+
+```rust
+rsx!{
+    div {
+        hidden: "false",
+        "hello"
+    }
+}
+```
+would actually render an output of 
+```html
+<div>hello</div> 
+```
+
+Notice how `hidden` is not present in the final output?
+
+Not all attributes work like this however. Only *these specific attributes* are whitelisted to have this behavior:
+
+- `allowfullscreen`
+- `allowpaymentrequest`
+- `async`
+- `autofocus`
+- `autoplay`
+- `checked`
+- `controls`
+- `default`
+- `defer`
+- `disabled`
+- `formnovalidate`
+- `hidden`
+- `ismap`
+- `itemscope`
+- `loop`
+- `multiple`
+- `muted`
+- `nomodule`
+- `novalidate`
+- `open`
+- `playsinline`
+- `readonly`
+- `required`
+- `reversed`
+- `selected`
+- `truespeed`
+
+For any other attributes, a value of `"false"` will be sent directly to the DOM.
+
+## Stopping form input and navigation with `prevent_default`
+
+Currently, calling `prevent_default` on events in EventHandlers is not possible from Desktop/Mobile. Until this is supported, it's possible to prevent default using the `prevent_default` attribute. 
+
+> Note: you cannot conditionally prevent default with this approach. This is a limitation until synchronous event handling is available across the Webview boundary 
+
+To use `prevent_default`, simply attach the `prevent_default` attribute to a given element and set it to the name of the event handler you want to prevent default on. We can attach this attribute multiple times for multiple attributes.
+
+```rust
+rsx!{
+    input {
+        oninput: move |_| {},
+        prevent_default: "oninput",
+
+        onclick: move |_| {},
+        prevent_default: "onclick",
+    }
+}
+```
+<!-- 
+## Passing attributes into children: `..Attributes`
+
+> Note: this is an experimental, unstable feature not available in released versions of Dioxus. Feel free to skip this section.
+
+Just like Dioxus supports spreading component props into components, we also support spreading attributes into elements. This lets you pass any arbitrary attributes through components into elements.
+
+
+```rust
+#[derive(Props)]
+pub struct InputProps<'a> {
+    pub children: Element<'a>,
+    pub attributes: Attribute<'a>
+}
+
+pub fn StateInput<'a>(cx: Scope<'a, InputProps<'a>>) -> Element {
+    cx.render(rsx! (
+        input {
+            ..cx.props.attributes,
+            &cx.props.children,
+        }
+    ))
+}
+``` -->
+
+## Controlled inputs and `value`, `checked`, and `selected`
+
+In Dioxus, there is a distinction between controlled and uncontrolled inputs. Most inputs you'll use are "controlled," meaning we both drive the `value` of the input and react to the `oninput`.
+
+Controlled components:
+```rust
+let value = use_state(&cx, || String::from("hello world"));
+
+rsx! {
+    input {
+        oninput: move |evt| value.set(evt.value.clone()),
+        value: "{value}",
+    }
+}
+```
+
+With uncontrolled inputs, we won't actually drive the value from the component. This has its advantages when we don't want to re-render the component when the user inputs a value. We could either select the element directly - something Dioxus doesn't support across platforms - or we could handle `oninput` and modify a value without causing an update:
+
+```rust
+let value = use_ref(&cx, || String::from("hello world"));
+
+rsx! {
+    input {
+        oninput: move |evt| *value.write_silent() = evt.value.clone(),
+        // no "value" is driven
+    }
+}
+```
+
+## Strings for handlers like `onclick`
+
+For element fields that take a handler like `onclick` or `oninput`, Dioxus will let you attach a closure. Alternatively, you can also pass a string using normal attribute syntax and assign this attribute on the DOM.
+
+This lets you escape into JavaScript (only if your renderer can execute JavaScript).
+
+```rust
+rsx!{
+    div {
+        // handle oninput with rust
+        oninput: move |_| {},
+
+        // or handle oninput with javascript
+        oninput: "alert('hello world')",
+    }
+}
+
+```
+
+## Wrapping up
+
+We've reached just about the end of what you can do with elements without venturing into "advanced" territory.
+
+In this chapter, we learned:
+- How to declare elements
+- How to conditionally render parts of your UI
+- How to render lists
+- Which attributes are "special"
+
+There's more to elements! For further reading, check out:
+
+- [Custom Elements]()

docs/guide/src/elements/vnodes.md

@@ -81,13 +81,13 @@ 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.
+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  square braces.
 
 ```rust
-rsx!( {[format_args!("Hello {}", if enabled { "Jack" } else { "Bob" } )]} )
+rsx!( {format_args!("Hello {}", if enabled { "Jack" } else { "Bob" } )] )
 ```
 
-Alternatively, `&str` can be included directly, though it must be inside of an array:
+Alternatively, `&str` can be included directly, though it must be inside of square braces:
 
 ```rust
 rsx!( "Hello ",  [if enabled { "Jack" } else { "Bob" }] )
@@ -170,4 +170,4 @@ We learned:
 - Elements can either be a named container or text
 - Some Elements have properties that the renderer can use to draw the UI to the screen
 
-Next, we'll compose Elements together to form components.
+Next, we'll compose Elements together using Rust-based logic.

docs/guide/src/interactivity/event_handlers.md

@@ -1 +1,3 @@
 # Event handlers
+
+> This section is currently under construction! 🏗

docs/guide/src/interactivity/hooks.md

@@ -76,6 +76,78 @@ This is why hooks called out of order will fail - if we try to downcast a `Hook<
 
 This pattern might seem strange at first, but it can be a significant upgrade over structs as blobs of state, which tend to be difficult to use in [Rust given the ownership system](https://rust-lang.github.io/rfcs/2229-capture-disjoint-fields.html).
 
+
+## Rules of hooks
+
+Hooks are sensitive to how they are used. To use hooks, you must abide by the
+"rules of hooks" (borrowed from react)](https://reactjs.org/docs/hooks-rules.html):
+
+- Functions with "use_" should not be called in callbacks
+- Functions with "use_" should not be called out of order
+- Functions with "use_" should not be called in loops or conditionals
+
+Examples of "no-nos" include:
+
+### ❌ Nested uses
+
+```rust
+// ❌ don't call use_hook or any `use_` function *inside* use_hook!
+cx.use_hook(|_| {
+    let name = cx.use_hook(|_| "ads");
+})
+
+// ✅ instead, move the first hook above
+let name = cx.use_hook(|_| "ads");
+cx.use_hook(|_| {
+    // do something with name here
+})
+```
+
+### ❌ Uses in conditionals
+```rust
+// ❌ don't call use_ in conditionals!
+if do_thing {
+    let name = use_state(&cx, || 0);
+}
+
+// ✅ instead, *always* call use_state but leave your logic
+let name = use_state(&cx, || 0);
+if do_thing {
+    // do thing with name here
+}
+```
+
+### ❌ Uses in loops
+
+
+```rust
+// ❌ Do not use hooks in loops!
+let mut nodes = vec![];
+
+for name in names {
+    let age = use_state(&cx, |_| 0);
+    nodes.push(cx.render(rsx!{
+        div { "{age}" }
+    }))
+}
+
+// ✅ Instead, consider refactoring your usecase into components 
+#[inline_props]
+fn Child(cx: Scope, name: String) -> Element {
+    let age = use_state(&cx, |_| 0);
+    cx.render(rsx!{ div { "{age}" } })
+}
+
+// ✅ Or, use a hashmap with use_ref
+```rust
+let ages = use_ref(&cx, |_| HashMap::new());
+
+names.iter().map(|name| {
+    let age = ages.get(name).unwrap();
+    cx.render(rsx!{ div { "{age}" } })
+})
+```
+
 ## Building new Hooks
 
 However, most hooks you'll interact with *don't* return an `&mut T` since this is not very useful in a real-world situation.
@@ -168,6 +240,7 @@ fn example(cx: Scope) -> Element {
 
 ```
 
+
 ## Hooks provided by the `Dioxus-Hooks` package
 
 By default, we bundle a handful of hooks in the Dioxus-Hooks package. Feel free to click on each hook to view its definition and associated documentation.

docs/guide/src/interactivity/importanthooks.md

@@ -0,0 +1,142 @@
+# `use_state` and `use_ref`
+
+Most components you will write in Dioxus will need to store state somehow. For local state, we provide two very convenient hooks:
+
+- `use_state`
+- `use_ref`
+
+Both of these hooks are extremely powerful and flexible, so we've dedicated this section to understanding them properly.
+
+> These two hooks are not the only way to store state. You can always build your own hooks!
+
+## Note on Hooks
+
+If you're struggling with errors due to usage in hooks, make sure you're following the rules of hooks:
+
+- Functions with "use_" should not be called in callbacks
+- Functions with "use_" should not be called out of order
+- Functions with "use_" should not be called in loops or conditionals
+
+A large majority of issues that seem to be "wrong with Dioxus" are actually just a misuse of hooks.
+
+## `use_state`
+
+The `use_state` hook is very similar to its React counterpart. When we use it, we get two values: 
+
+- The value itself as an `&T`
+- A handle to set the value `&UseState<T>`
+
+```rust
+let (count, set_count) = use_state(&cx, || 0);
+
+// then to set the count
+set_count(count + 1)
+```
+
+However, the `set_count` object is more powerful than it looks. You can use it as a closure, but you can also call methods on it to do more powerful operations.
+
+For instance, we can get a handle to the current value at any time:
+
+```rust
+let current: Rc<T> = set_count.current();
+```
+
+Or, we can get the inner handle to set the value
+
+```rust
+let setter: Rc<dyn Fn(T)> = set_count.setter();
+```
+
+Or, we can set a new value using the current value as a reference:
+
+```rust
+set_count.modify(|i| i + 1);
+```
+
+If the value is cheaply cloneable, then we can call `with_mut` to get a mutable reference to the value:
+
+```rust
+set_count.with_mut(|i| *i += 1);
+```
+
+Alternatively, we can call `make_mut` which gives us a `RefMut` to the underlying value:
+
+```rust
+*set_count.make_mut() += 1;
+```
+
+Plus, the `set_count` handle is cloneable into async contexts, so we can use it in futures.
+
+```rust
+// count up infinitely
+cx.spawn({
+    to_owned![set_count]; 
+    async move {
+        loop {
+            wait_ms(100).await;
+            set_count.modify(|i| i + 1);
+        }
+    }
+})
+```
+
+## `use_ref`
+
+You might've noticed a fundamental limitation to `use_state`: to modify the value in-place, it must be cheaply cloneable. But what if your type is not cheap to clone?
+
+In these cases, you should reach for `use_ref` which is essentially just a glorified `Rc<RefCell<T>>` (typical Rust UI shenanigans).
+
+This provides us some runtime locks around our data, trading reliability for performance. For most cases though, you will find it hard to make `use_ref` crash.
+
+> Note: this is *not* exactly like its React counterpart since calling `write` will cause a re-render. For more React parity, use the `write_silent` method.
+
+To use the hook:
+
+```rust
+let names = use_ref(&cx, || vec!["susie", "calvin"]);
+```
+
+To read the hook values, use the `read()` method:
+
+```rust
+cx.render(rsx!{
+    ul {
+        names.read().iter().map(|name| {
+            rsx!{ "{name}" }
+        })
+    }
+})
+```
+
+And then to write into the hook value, use the `write` method:
+
+```rust
+names.write().push("Tiger");
+```
+
+If you don't want to re-render the component when names is updated, then we can use the `write_silent` method:
+
+```rust
+names.write().push("Transmogrifier");
+```
+
+Again, like `UseState`, the `UseRef` handle is clonable into async contexts:
+
+
+```rust
+// infinitely push calvin into the list
+cx.spawn({
+    to_owned![names]; 
+    async move {
+        loop {
+            wait_ms(100).await;
+            names.write().push("Calvin");
+        }
+    }
+})
+```
+
+
+## Wrapping up
+
+These two hooks are extremely powerful at storing state.

docs/guide/src/interactivity/index.md

@@ -64,7 +64,7 @@ The most common hook you'll use for storing state is `use_state`. `use_state` pr
 
 ```rust
 fn App(cx: Scope)-> Element {
-    let post = use_state(&cx, || {
+    let (post, set_post) = use_state(&cx, || {
         PostData {
             id: Uuid::new_v4(),
             score: 10,
@@ -84,10 +84,10 @@ fn App(cx: Scope)-> Element {
 }
 ```
 
-Whenever we have a new post that we want to render, we can call `set` on `post` and provide a new value:
+Whenever we have a new post that we want to render, we can call `set_post` and provide a new value:
 
 ```rust
-post.set(PostData {
+set_post(PostData {
     id: Uuid::new_v4(),
     score: 20,
     comment_count: 0,
@@ -112,11 +112,11 @@ For example, let's say we provide a button to generate a new post. Whenever the
 
 ```rust
 fn App(cx: Scope)-> Element {
-    let post = use_state(&cx, || PostData::new());
+    let (post, set_post) = use_state(&cx, || PostData::new());
 
     cx.render(rsx!{
         button {
-            on_click: move |_| post.set(PostData::random())
+            on_click: move |_| set_post(PostData::random())
             "Generate a random post"
         }
         Post { props: &post }
@@ -128,7 +128,12 @@ We'll dive much deeper into event listeners later.
 
 ### Updating state asynchronously
 
-We can also update our state outside of event listeners with `coroutines`. `Coroutines` are asynchronous blocks of our component that have the ability to cleanly interact with values, hooks, and other data in the component. Since coroutines stick around between renders, the data in them must be valid for the `'static` lifetime. We must explicitly declare which values our task will rely on to avoid the `stale props` problem common in React.
+We can also update our state outside of event listeners with `futures` and `coroutines`. 
+
+- `Futures` are Rust's version of promises that can execute asynchronous work by an efficient polling system. We can submit new futures to Dioxus either through `push_future` which returns a `TaskId` or with `spawn`.
+- `Coroutines` are asynchronous blocks of our component that have the ability to cleanly interact with values, hooks, and other data in the component. 
+
+Since coroutines and Futures stick around between renders, the data in them must be valid for the `'static` lifetime. We must explicitly declare which values our task will rely on to avoid the `stale props` problem common in React.
 
 We can use tasks in our components to build a tiny stopwatch that ticks every second.
 
@@ -136,14 +141,14 @@ We can use tasks in our components to build a tiny stopwatch that ticks every se
 
 ```rust
 fn App(cx: Scope)-> Element {
-    let mut sec_elapsed = use_state(&cx, || 0);
+    let (elapsed, set_elapsed) = use_state(&cx, || 0);
 
     use_future(&cx, || {
-        let mut sec_elapsed = sec_elapsed.for_async();
+        to_owned![set_elapsed]; // explicitly capture this hook for use in async
         async move {
             loop {
                 TimeoutFuture::from_ms(1000).await;
-                sec_elapsed += 1;
+                set_elapsed.modify(|i| i + 1)
             }
         }
     });
@@ -152,12 +157,10 @@ fn App(cx: Scope)-> Element {
 }
 ```
 
-Using asynchronous code can be difficult! This is just scratching the surface of what's possible. We have an entire chapter on using async properly in your Dioxus Apps.
+Using asynchronous code can be difficult! This is just scratching the surface of what's possible. We have an entire chapter on using async properly in your Dioxus Apps. We have an entire section dedicated to using `async` properly later in this book.
 
 ### How do I tell Dioxus that my state changed?
 
-So far, we've only updated our state with `.set`. However, you might've noticed that we used `AddAssign` to increment the `sec_elapsed` value in our stopwatch example *without* calling set. This is because the `AddAssign` trait is implemented for `UseState<T>` (the wrapper around our value returned from `use_state`). Under the hood, whenever you try to mutate our value through `UseState`, you're actually calling `.set` which informs Dioxus that _this_ component needs to be updated on the screen.
-
 Whenever you inform Dioxus that the component needs to be updated, it will "render" your component again, storing the previous and current Elements in memory. Dioxus will automatically figure out the differences between the old and the new and generate a list of edits that the renderer needs to apply to change what's on the screen. This process is called "diffing":
 
 ![Diffing](../images/diffing.png)
@@ -170,7 +173,7 @@ With these building blocks, we can craft new hooks similar to `use_state` that l
 
 In general, Dioxus should be plenty fast for most use cases. However, there are some rules you should consider following to ensure your apps are quick.
 
-- 1) **Don't call set—state _while rendering_**. This will cause Dioxus to unnecessarily re-check the component for updates.
+- 1) **Don't call set—state _while rendering_**. This will cause Dioxus to unnecessarily re-check the component for updates or enter an infinite loop.
 - 2) **Break your state apart into smaller sections.** Hooks are explicitly designed to "unshackle" your state from the typical model-view-controller paradigm, making it easy to reuse useful bits of code with a single function.
 - 3) **Move local state down**. Dioxus will need to re-check child components of your app if the root component is constantly being updated. You'll get best results if rapidly-changing state does not cause major re-renders.
 

docs/guide/src/interactivity/lifecycles.md

@@ -1 +1,3 @@
 # Lifecycle, updates, and effects
+
+> This section is currently under construction! 🏗

docs/guide/src/interactivity/user_input.md

@@ -1 +1,6 @@
 # User Input and Controlled Components
+
+Handling user input is one of the most common things your app will do, but it can be tricky
+
+
+> This section is currently under construction! 🏗

docs/guide/src/setup.md

@@ -19,7 +19,7 @@ Dioxus requires a few main things to get up and running:
 
 Dioxus integrates very well with the Rust-Analyzer IDE plugin which will provide appropriate syntax highlighting, code navigation, folding, and more.
 
-### Installing Rust
+## Installing Rust
 
 Head over to [https://rust-lang.org](http://rust-lang.org) and install the Rust compiler.
 
@@ -29,24 +29,39 @@ Once installed, make sure to install wasm32-unknown-unknown as a target if you'r
 rustup target add wasm32-unknown-unknown
 ```
 
-### Platform-Specific Dependencies
+## Platform-Specific Dependencies
 
 If you are running a modern, mainstream operating system, you should need no additional setup to build WebView-based Desktop apps. However, if you are running an older version of Windows or a flavor of Linux with no default web rendering engine, you might need to install some additional dependencies.
 
-For windows users: download the [bootstrapper for Webview2 from Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
 
-For linux users, we need the development libraries for libgtk.
+### Windows
+
+Windows Desktop apps depend on WebView2 - a library which should be installed in all modern Windows distributions. If you have Edge installed, then Dioxus will work fine. If you *don't* have Webview2, [then you can install it through Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/webview2/). MS provides 3 options:
+
+1. A tiny "evergreen" *bootstrapper* which will fetch an installer from Microsoft's CDN
+2. A tiny *installer* which will fetch Webview2 from Microsoft's CDN
+3. A statically linked version of Webview2 in your final binary for offline users
+
+For development purposes, use Option 1. 
+
+### Linux
+
+Webview Linux apps require WebkitGtk. When distributing, this can be part of your dependency tree in your `.rpm` or `.deb`. However, it's very likely that your users will already have WebkitGtk.
 
 ```
 sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libappindicator3-dev
 ```
 
-When distributing onto older Windows platforms or less-mainstream 
 
+If you run into issues, make sure you have all the basics installed, as outlined in the [Tauri docs](https://tauri.studio/en/docs/get-started/setup-linux).
+
+
+### macOS
 
+Currently - everything for macOS is built right in! However, you might run into an issue if you're using nightly Rust due to some permissions issues in our Tao dependency (which have been resolved but not published).
 
 
-### Dioxus-CLI for dev server, bundling, etc.
+## 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. To install the CLI, you'll need cargo (which should be automatically installed with Rust):
 
@@ -62,7 +77,7 @@ $ cargo install --force dioxus-cli
 
 We provide this 1st-party tool to save you from having to run potentially untrusted code every time you add a crate to your project - as is standard in the NPM ecosystem.
 
-### Suggested extensions
+## Suggested extensions
 
 If you want to keep your traditional `npm install XXX` workflow for adding packages, you might want to install `cargo-edit` and a few other fun `cargo` extensions:
 

docs/guide/src/state/errorhandling.md

@@ -9,3 +9,4 @@ fn App((cx, props): Component) -> Element {
 }
 ```
 
+> This section is currently under construction! 🏗

docs/guide/src/state/index.md

@@ -4,5 +4,25 @@ Every app you'll build with Dioxus will have some sort of state that needs to be
 
 In this chapter, we'll cover the various ways to manage state, the appropriate terminology, various patterns, and then take an overview
 
+## Terminology 
+
+
+> This section is currently under construction! 🏗
+
+
+
+
+## Important hook: `use_state`
+
+
+
+
+
+## Important hook: `use_ref`
+
+
+
+
+## `provide_context` and `consume_context`
 
 ## Terminology

docs/guide/src/state/liftingstate.md

@@ -1 +1,4 @@
 # Lifting State
+
+
+> This section is currently under construction! 🏗

docs/guide/src/state/localstate.md

@@ -1 +1,4 @@
 # Local State
+
+
+> This section is currently under construction! 🏗

docs/guide/src/state/sharedstate.md

@@ -1 +1,7 @@
 # Global State
+
+
+cx.provide_context()
+cx.consume_context()
+
+> This section is currently under construction! 🏗

docs/guide/src/tutorial/components.md

@@ -1 +1,3 @@
 # Defining Components
+
+This section is currently under construction! 🏗

docs/guide/src/tutorial/state.md

@@ -1 +1,3 @@
 # Defining State
+
+This section is currently under construction! 🏗

docs/guide/src/tutorial/structure.md

@@ -1 +1,4 @@
 # Structuring our app
+
+
+This section is currently under construction! 🏗

docs/guide/src/tutorial/styling.md

@@ -1 +1,4 @@
 # Styling
+
+
+This section is currently under construction! 🏗

docs/router/.gitignore

@@ -0,0 +1 @@
+book

docs/router/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Jonathan Kelley"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Dioxus Router"

docs/router/src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [Chapter 1](./chapter_1.md)

docs/router/src/chapter_1.md

@@ -0,0 +1 @@
+# Chapter 1