docs: update references

Cargo.toml

@@ -20,8 +20,8 @@ dioxus-web = { path = "./packages/web", version = "^0.0.2", optional = true }
 dioxus-desktop = { path = "./packages/desktop", version = "^0.1.1", optional = true }
 dioxus-ssr = { path = "./packages/ssr", version = "0.1.1", optional = true }
 
-# dioxus-router = { path = "./packages/router", optional = true }
+dioxus-router = { path = "./packages/router", optional = true }
-# dioxus-mobile = { path = "./packages/mobile", optional = true }
+dioxus-mobile = { path = "./packages/mobile", optional = true }
 # dioxus-liveview = { path = "./packages/liveview", optional = true }
 
 [features]
@@ -33,8 +33,8 @@ html = ["dioxus-html"]
 ssr = ["dioxus-ssr"]
 web = ["dioxus-web"]
 desktop = ["dioxus-desktop"]
+router = ["dioxus-router"]
 
-# router = ["dioxus-router"]
 # "dioxus-router/web"
 # "dioxus-router/desktop"
 # desktop = ["dioxus-desktop", "dioxus-router/desktop"]

README.md

@@ -91,12 +91,12 @@ cargo run --features desktop --example EXAMPLE
 
 <table style="width:100%" align="center">
     <tr >
-        <th><a href="https://dioxuslabs.com/guide/">Web</a></th>
+        <th><a href="https://dioxuslabs.com/guide/">Tutorial</a></th>
-        <th><a href="https://dioxuslabs.com/guide/">Desktop</a></th>
+        <th><a href="https://dioxuslabs.com/reference/web">Web</a></th>
-        <th><a href="https://dioxuslabs.com/guide/">Mobile</a></th>
+        <th><a href="https://dioxuslabs.com/reference/desktop/">Desktop</a></th>
-        <th><a href="https://dioxuslabs.com/guide/">TUI</a></th>
+        <th><a href="https://dioxuslabs.com/reference/ssr/">SSR</a></th>
-        <th><a href="https://dioxuslabs.com/guide/">State</a></th>
+        <th><a href="https://dioxuslabs.com/reference/mobile/">Mobile</a></th>
-        <th><a href="https://dioxuslabs.com/guide/">Tools</a></th>
+        <th><a href="https://dioxuslabs.com/guide/concepts/managing_state.html">State</a></th>
     <tr>
 </table>
 

docs/reference/.gitignore

@@ -0,0 +1 @@
+reference

docs/reference/src/README.md

@@ -0,0 +1,27 @@
+# Dioxus: Reference and Advanced Guides
+
+![dioxuslogo](./images/dioxuslogo_full.png)
+
+**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 started with Dioxus running on the Web, Desktop, Mobile, and more.
+
+> This book is the reference and Advanced Guides for the Dioxus framework. For a tutorial on how to actually *use* Dioxus, make sure to check out the [official guide](https://dioxuslabs.com/guide/).
+
+
+## Reference and Guides
+
+With the reference, we aim to maintain documentation of functionality that might not be mentioned in the official guide to keep the information load to a minimum. Some topics not included by the guide but discussed in the reference include:
+
+- ThreadSafety of the VirtualDom
+- Full usage of `rsx!` and included features
+- Spread pattern for component properties
+- Testing
+- Memoization in Depth
+- Custom Elements
+- Custom Renderers
+
+
+## Contributing
+
+If this doc is lacking in any way, is confusing, has a typo, or you'd just like to help improve things, feel free to make a PR against the [Dioxus repo](https://github.com/DioxusLabs/dioxus/tree/master/docs/reference).
+
+All contributions will be licensed under MIT/Apache2.

docs/reference/src/SUMMARY.md

@@ -2,60 +2,42 @@
 
 - [Introduction](README.md)
 
-- [Web](web/intro.md)
+- [Web](web/index.md)
-  - [Getting Started](web/setup.md)
+- [Desktop](desktop/index.md)
-  - [Events](concepts/errorhandling.md)
+- [Mobile](mobile/index.md)
-
+- [SSR](ssr/index.md)
-- [Desktop](desktop/intro.md)
+- [TUI](tui/index.md)
-  - [Getting Started](desktop/setup.md)
-  - [events](desktop/.md)
-
-- [Mobile](concepts/managing_state.md)
-  - [Getting Started](concepts/sharedstate.md)
-  - [Specifics](concepts/errorhandling.md)
-
-- [Working with Async](concepts/async.md)
   
-- [Code Reference]()
+- [Advanced Guides](guide/index.md)
-  - [Code Reference]()
+  - [RSX in Depth](guide/rsx_in_depth.md)
-  - [Code Reference]()
+  - [Components](guide/components.md)
-  - [Code Reference]()
+  - [Props](guide/props.md)
-  - [Code Reference]()
+  - [Memoization](guide/memoization.md)
+  - [Performance](guide/performance.md)
+  - [Testing](guide/testing.md)
+  - [Building Elements with NodeFactory](guide/rsx.md)
+  - [Custom Elements](guide/custom_elements.md)
+  - [Custom Renderer](guide/custom_renderer.md)
+  - [Server-side components](guide/server_side_components.md)
+  - [Bundling and Distributing](guide/bundline.md)
 
-- [Topics in Depth](depth/topics.md)
+- [Reference Guide](reference/reference.md)
-  - [RSX](depth/rsx.md)
+  - [Anti-patterns](reference/anti.md)
-  - [Components](depth/components.md)
+  - [Children](reference/children.md)
-  - [Props](depth/props.md)
+  - [Conditional Rendering](reference/conditional.md)
-  - [Memoization](depth/memoization.md)
+  - [Controlled Inputs](reference/controlled.md)
-  - [Performance](depth/performance.md)
+  - [Custom Elements](reference/custom.md)
-  - [Testing](depth/testing.md)
+  - [Empty Components](reference/empty.md)
-
+  - [Error Handling](reference/error.md)
-- [Advanced Guides](tutorial/advanced_guides.md)
+  - [Fragments](reference/fragments.md)
-  - [Memoization](concepts/memoization.md)
+  - [Global CSS](reference/global.md)
-  - [RSX in Depth](concepts/rsx_in_depth.md)
+  - [Inline Styles](reference/inline.md)
-  - [Building Elements with NodeFactory](concepts/rsx.md)
+  - [Iterators](reference/iterators.md)
-  - [Custom Elements](concepts/custom_elements.md)
+  - [Listeners](reference/listeners.md)
-  - [Custom Renderer](concepts/custom_renderer.md)
+  - [Memoization](reference/memoization.md)
-  - [Server-side components](concepts/server_side_components.md)
+  - [Node Refs](reference/node.md)
-  - [Bundling and Distributing](concepts/bundline.md)
+  - [Spread Pattern](reference/spread.md)
-
+  - [State Management](reference/state.md)
-- [Reference Guide]()
+  - [Suspense](reference/suspense.md)
-  - [Anti-patterns]()
+  - [task](reference/task.md)
-  - [Children]()
+  - [Testing](reference/testing.md)
-  - [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/reference/src/desktop/index.md

@@ -0,0 +1,6 @@
+# Desktop
+
+
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/guide/bundline.md

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

docs/reference/src/guide/components.md

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

docs/reference/src/guide/custom_elements.md

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

docs/reference/src/guide/custom_renderer.md

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

docs/reference/src/guide/index.md

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

docs/reference/src/guide/memoization.md

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

docs/reference/src/guide/performance.md

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

docs/reference/src/guide/props.md

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

docs/reference/src/guide/rsx.md

@@ -0,0 +1 @@
+# Building Elements with NodeFactory

docs/reference/src/guide/rsx_in_depth.md

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

docs/reference/src/guide/server_side_components.md

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

docs/reference/src/guide/testing.md

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

docs/reference/src/mobile/index.md

@@ -0,0 +1,4 @@
+# Mobile
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/mobile/intro.md

@@ -0,0 +1,4 @@
+# Mobile
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/ssr/index.md

@@ -0,0 +1,4 @@
+# SSR
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/ssr/intro.md

@@ -0,0 +1,4 @@
+# SSR
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/tui/index.md

@@ -0,0 +1 @@
+# TUI

docs/reference/src/tui/intro.md

@@ -0,0 +1,4 @@
+# TUI
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/web/index.md

@@ -0,0 +1,109 @@
+# Getting Started: Dioxus for Web
+
+[*"Pack your things, we're going on an adventure!"*](https://trunkrs.dev)
+
+Dioxus is well supported for the web through WebAssembly. A build of Dioxus for the web will be roughly equivalent to the size of a React build (70kb vs 65kb), but will load significantly faster due to [WebAssembly's StreamingCompile](https://hacks.mozilla.org/2018/01/making-webassembly-even-faster-firefoxs-new-streaming-and-tiering-compiler/) option.
+
+Building Dioxus apps for the web requires much less configuration than our JavaScript counterparts.
+
+## Tooling
+
+To develop your Dioxus app for the web, you'll need a tool to build and serve your assets. We recommend using [trunk](https://trunkrs.dev) which includes a build system, Wasm optimization, a dev server, and support for SASS/CSS.
+
+Currently, trunk projects can only build the root binary (ie the `main.rs`). To build a new Dioxus compatible project, this should get you up and running.
+
+First, [install trunk](https://trunkrs.dev/#install):
+```shell
+$ cargo install trunk
+```
+
+Make sure the `wasm32-unknown-unknown` target is installed:
+```shell
+$ rustup target add wasm32-unknown-uknown
+```
+
+Create a new project:
+
+```shell
+$ cargo new --bin demo
+$ cd demo
+```
+
+Add Dioxus with the `web` features:
+
+```
+$ cargo add dioxus --features web
+```
+
+Add an `index.html` for Trunk to use. Make sure your "mount point" element has an ID of "main" (this can be configured later):
+
+```html
+<html>
+  <head>
+    <meta content="text/html;charset=utf-8" http-equiv="Content-Type" name="viewport" content="width=device-width, initial-scale=1.0" charset="UTF-8">
+  </head>
+  <body>
+    <div id="main"> </div>
+  </body>
+</html>
+```
+
+Edit your `main.rs`:
+```rust
+// main.rs
+
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::web::launch(app);
+}
+
+fn app(cx: Scope) -> Element {
+    cx.render(rsx!{
+        div { "hello, wasm!" }
+    })
+}
+```
+
+
+And to serve our app:
+
+```shell
+trunk serve
+```
+
+To build our app and publish it to Github:
+
+- Make sure Github Pages is set up for your repo
+- Build your app with `trunk build --release`
+- Move your generated HTML/CSS/JS/Wasm from `dist` into the folder configured for Github Pages
+- Add and commit with git
+- Push to Github
+
+That's it!
+
+## Future Build Tool
+
+We are currently working on our own build tool called [Dioxus Studio](http://github.com/dioxusLabs/studio) which will support:
+- an interactive TUI
+- on-the-fly reconfiguration
+- hot CSS reloading
+- two-way data binding between browser and source code
+- an interpreter for `rsx!` 
+- ability to publish to github/netlify/vercel
+- bundling for iOS/Desktop/etc
+
+## Features
+
+Currently, the web supports:
+
+- Pre-rendering/Hydration
+
+## Events
+
+The regular events in the `html` crate work just fine in the web.
+
+
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!

docs/reference/src/web/intro.md

@@ -0,0 +1,109 @@
+# Getting Started: Dioxus for Web
+
+[*"Pack your things, we're going on an adventure!"*](https://trunkrs.dev)
+
+Dioxus is well supported for the web through WebAssembly. A build of Dioxus for the web will be roughly equivalent to the size of a React build (70kb vs 65kb), but will load significantly faster due to [WebAssembly's StreamingCompile](https://hacks.mozilla.org/2018/01/making-webassembly-even-faster-firefoxs-new-streaming-and-tiering-compiler/) option.
+
+Building Dioxus apps for the web requires much less configuration than our JavaScript counterparts.
+
+## Tooling
+
+To develop your Dioxus app for the web, you'll need a tool to build and serve your assets. We recommend using [trunk](https://trunkrs.dev) which includes a build system, Wasm optimization, a dev server, and support for SASS/CSS.
+
+Currently, trunk projects can only build the root binary (ie the `main.rs`). To build a new Dioxus compatible project, this should get you up and running.
+
+First, [install trunk](https://trunkrs.dev/#install):
+```shell
+$ cargo install trunk
+```
+
+Make sure the `wasm32-unknown-unknown` target is installed:
+```shell
+$ rustup target add wasm32-unknown-uknown
+```
+
+Create a new project:
+
+```shell
+$ cargo new --bin demo
+$ cd demo
+```
+
+Add Dioxus with the `web` features:
+
+```
+$ cargo add dioxus --features web
+```
+
+Add an `index.html` for Trunk to use. Make sure your "mount point" element has an ID of "main" (this can be configured later):
+
+```html
+<html>
+  <head>
+    <meta content="text/html;charset=utf-8" http-equiv="Content-Type" name="viewport" content="width=device-width, initial-scale=1.0" charset="UTF-8">
+  </head>
+  <body>
+    <div id="main"> </div>
+  </body>
+</html>
+```
+
+Edit your `main.rs`:
+```rust
+// main.rs
+
+use dioxus::prelude::*;
+
+fn main() {
+    dioxus::web::launch(app);
+}
+
+fn app(cx: Scope) -> Element {
+    cx.render(rsx!{
+        div { "hello, wasm!" }
+    })
+}
+```
+
+
+And to serve our app:
+
+```shell
+trunk serve
+```
+
+To build our app and publish it to Github:
+
+- Make sure Github Pages is set up for your repo
+- Build your app with `trunk build --release`
+- Move your generated HTML/CSS/JS/Wasm from `dist` into the folder configured for Github Pages
+- Add and commit with git
+- Push to Github
+
+That's it!
+
+## Future Build Tool
+
+We are currently working on our own build tool called [Dioxus Studio](http://github.com/dioxusLabs/studio) which will support:
+- an interactive TUI
+- on-the-fly reconfiguration
+- hot CSS reloading
+- two-way data binding between browser and source code
+- an interpreter for `rsx!` 
+- ability to publish to github/netlify/vercel
+- bundling for iOS/Desktop/etc
+
+## Features
+
+Currently, the web supports:
+
+- Pre-rendering/Hydration
+
+## Events
+
+The regular events in the `html` crate work just fine in the web.
+
+
+## Future Steps
+
+Make sure to read the [Dioxus Guide](https://dioxuslabs.com/guide) if you already haven't!