Improve inline docs (#2460)

Improve inline docs * improve incorrect event handler return error message * Improve event handler docs * document the eval functions * document spawn and common spawn errors * fix event handler docs * add notes about how you use attributes and elements in rsx * add doc aliases for attributes and events we rename * add some more aliases for common search terms * don't doc ignore any public examples in core * don't ignore public doc examples in ssr * don't ignore examples in the dioxus package readme * add a warning when you launch without a renderer enabled * fix some outdated element docs * add a bunch of examples to resource * add notes about desktop events * add more docs for use_resource * add on_unimplemented hint to Dependency * fix some unresolved links * add examples to each of the router traits * add not implemented errors for router traits * add an example to the routable trait * expand rsx macro docs * improve memo docs * update the dioxus readme * mention dioxus crate features in the docs * fix a bunch of doc tests * fix html doc tests * fix router doc tests * fix dioxus signals doc tests * fix dioxus ssr doc tests * fix use_future example in the hooks cheat sheet * add a javascript alias for eval * fix hook explanation values * remove unused embed-doc-image dependency
2024-06-06 18:15:17 -07:00
1 parent 054351139f
commit 0127501dbf
@@ -21,7 +21,7 @@

 ## Overview

-`dioxus-hooks` includes some basic useful hooks for dioxus such as:
+`dioxus-hooks` includes some basic useful hooks for Dioxus such as:

 - use_signal
 - use_effect
@@ -29,8 +29,40 @@
 - use_memo
 - use_coroutine

+Unlike React, none of these hooks are foundational since they all build off the primitive `use_hook`. You can extend these hooks with [custom hooks](https://dioxuslabs.com/learn/0.5/cookbook/state/custom_hooks) in your own code. If you think they would be useful for the broader community, you can open a PR to add your hook to the [Dioxus Awesome](https://github.com/DioxusLabs/awesome-dioxus) list.

-Unlike React, none of these hooks are foundational since they all build off the primitive `use_hook`.
+## State Cheat Sheet
+
+If you aren't sure what hook to use, you can use this cheat sheet to help you decide:
+
+### State Location
+
+Depending on where you need to access the state, you can put your state in one of three places:
+
+| Location                                                                                 | Where can you access the state? | Recommended for Libraries? | Examples                                                                    |
+| ---------------------------------------------------------------------------------------- | ------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
+| [Hooks](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_signal.html)             | Any components you pass it to   | ✅                         | `use_signal(\|\| 0)`, `use_memo(\|\| state() * 2)`                          |
+| [Context](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_context_provider.html) | Any child components            | ✅                         | `use_context_provider(\|\| Signal::new(0))`, `use_context::<Signal<i32>>()` |
+| [Global](https://docs.rs/dioxus/latest/dioxus/prelude/struct.Signal.html#method.global)  | Anything in your app            | ❌                         | `Signal::global(\|\| 0)`                                                    |
+
+### Derived State
+
+If you don't have an initial value for your state, you can derive your state from other states with a closure or asynchronous function:
+
+| Hook                                                                                | Reactive (reruns when dependencies change) | Async | Memorizes Output | Example                                                                             |
+| ----------------------------------------------------------------------------------- | ------------------------------------------ | ----- | ---------------- | ----------------------------------------------------------------------------------- |
+| [`use_memo`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_memo.html)         | ✅                                         | ❌    | ✅               | `use_memo(move \|\| count() * 2)`                                                   |
+| [`use_resource`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_resource.html) | ✅                                         | ✅    | ❌               | `use_resource(move \|\| reqwest::get(format!("/users/{user_id}")))`                 |
+| [`use_future`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_future.html)     | ❌                                         | ✅    | ❌               | `use_future(move \|\| println!("{:?}", reqwest::get(format!("/users/{user_id}"))))` |
+
+### Persistent State
+
+The core hooks library doesn't provide hooks for persistent state, but you can extend the core hooks with hooks from [dioxus-sdk](https://crates.io/crates/dioxus-sdk) and the [dioxus-router](https://crates.io/crates/dioxus-router) to provide persistent state management.
+
+| State                                                                              | Sharable | Example                                                                                           |
+| ---------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| [`use_persistent`](https://github.com/DioxusLabs/sdk/tree/master/examples/storage) | ❌       | `use_persistent("unique_key", move \|\| initial_state)`                                           |
+| [`Router<Route> {}`](https://dioxuslabs.com/learn/0.5/router)                      | ✅       | `#[derive(Routable, Clone, PartialEq)] enum Route { #[route("/user/:id")] Homepage { id: u32 } }` |

 ## Contributing