diff --git a/docs/main-concepts/00-index.md b/docs/main-concepts/00-index.md index b4d938cae..19070c57e 100644 --- a/docs/main-concepts/00-index.md +++ b/docs/main-concepts/00-index.md @@ -1,3 +1,40 @@ -# Getting Started +# Dioxus Chapter 0 - Intro + Index -This page is an overview of the Dioxus documentation. +## Guides + +--- + +| Chapter | Description | +| ------------------ | ------------------------------------------ | +| 1-hello-world | Intro to Dioxus | +| 2-utilities | Tools to make writing apps easier | +| 3-vnode-macros | VNodes and the html! macro | +| 4-hooks | Renderer + event integration using web_sys | +| 5-context-api | Virtual DOM, patching/diffing | +| 6-subscription API | Standard bundle of useful hooks | +| 7-hello-world | Html + functional_component macro | +| 8-hello-world | Blessed state management solutions | +| 9-hello-world | Renderer + event integration using web_sys | +| 10-hello-world | Renderer + event integration using web_sys | + +## Development + +--- + +| Package | Use | +| ------- | ------------------------------------------------ | +| full | Batteries-included entrypoint with feature flags | +| core | Virtual DOM, diffing, patching, and events | +| hooks | Standard hooks | +| macro | Html + functional_component macro | +| web | Renderer + event integration using web_sys | +| live | Dedicated isomorphic framework | +| recoil | Data-flow-graph state management | +| redux | Reducer-style state management | +| bearly | Simple and idiomatic state management | + +## Books + +--- + +Book of patterns diff --git a/docs/main-concepts/03-rsx.md b/docs/main-concepts/03-rsx.md index 0b94d7e8f..460e67f33 100644 --- a/docs/main-concepts/03-rsx.md +++ b/docs/main-concepts/03-rsx.md @@ -11,8 +11,11 @@ There is also limited support for dynamic handlers, but it will function similar You'll want to write RSX where you can, and in a future release we'll have a tool that automatically converts HTML to RSX. ```rust -#[fc] -fn Example(cx: Context, name: &str, pending: bool, count: i32 ) -> VNode { +#[derive(PartialEq, Props)] +struct ExampleProps { name: &str, pending: bool, count: i32 } + +fn Example(cx: Context ) -> VNode { + let ExampleProps { name, pending, count } = cx.props; cx.render(html! {

"Hello, {name}!"

@@ -25,52 +28,42 @@ fn Example(cx: Context, name: &str, pending: bool, count: i32 ) -> VNode { ## rsx! macro -The rsx! macro is a VNode builder macro designed especially for Rust programs. Writing these should feel very natural, much like assembling a struct. VSCode also supports these with code folding, bracket-tabbing, bracket highlighting, and section selecting. +The rsx! macro is a VNode builder macro designed especially for Rust programs. Writing these should feel very natural, much like assembling a struct. VSCode also supports these with code folding, bracket-tabbing, bracket highlighting, section selecting, inline documentation, and GOTO definition (no rename support yet 😔 ). The Dioxus VSCode extension will eventually provide a macro to convert a selection of html! template and turn it into rsx!, so you'll never need to transcribe templates by hand. -It's also a bit easier on the eyes 🙂. +It's also a bit easier on the eyes 🙂 than HTML. ```rust -#[fc] -fn Example(cx: Context, name: &str, pending: bool, count: i32 ) -> VNode { +fn Example(cx: Context) -> VNode { cx.render(rsx! { div { - p {"Hello, {name}!"} - p {"Status: {pending}!"} - p {"Count {count}!"} + // cx derefs to props so you can access fields directly + p {"Hello, {cx.name}!"} + p {"Status: {cx.pending}!"} + p {"Count {cx.count}!"} } }) } - ``` Each element takes a comma-separated list of expressions to build the node. Roughly, here's how they work: -- `name: value` sets the property on this element. +- `name: value` sets a property on this element. - `"text"` adds a new text element - `tag {}` adds a new child element - `CustomTag {}` adds a new child component -- `{expr}` pastes the `expr` tokens literally. They must be IntoCtx to work properly +- `{expr}` pastes the `expr` tokens literally. They must be `IntoIterator where T: IntoVnode` to work properly Commas are entirely optional, but might be useful to delineate between elements and attributes. -The `render` function provides an **extremely efficient** allocator for VNodes and text, so try not to use the `format!` macro in your components. Rust's default `ToString` methods pass through the global allocator, but all text in components is allocated inside a manually-managed Bump arena. +The `render` function provides an **extremely efficient** allocator for VNodes and text, so try not to use the `format!` macro in your components. Rust's default `ToString` methods pass through the global allocator, but all text in components is allocated inside a manually-managed Bump arena. To push you in the right direction, all text-based attributes take `std::fmt::Arguments` directly, so you'll want to reach for `format_args!` when the built-in `f-string` interpolation just doesn't cut it. ```rust static Example: FC<()> = |cx| { let text = "example"; - let g = async { - wait(10).await; - "hello" - }; - - let user_name = use_read_async(cx, USERNAME); - let title = cx.suspend(user_name, |user_name| rsx!{ h1 { "Welcome back, {user_name}" } }); - - cx.render(rsx!{ div { h1 { "Example" }, @@ -92,12 +85,7 @@ static Example: FC<()> = |cx| { // `class` is not a restricted keyword unlike JS and ClassName class: "big small wide short {text}", - // bool-based classnames - classes: [("big", true), ("small", false)] - - // Bool-based props - // *must* be in the tuple form, cannot enter as a variable - tag: ("type", false) + class: format_args!("attributes take fmt::Arguments. {}", 99) tag: {"these tokens are placed directly"} @@ -133,9 +121,6 @@ static Example: FC<()> = |cx| { // Optionals {true.and_then(|f| rsx!{ h1 {"Conditional Rendering"} })} - // Bool options - {(rsx!{ h1 {"Conditional Rendering"}, true)} - // Child nodes // Returns &[VNode] {cx.children()} diff --git a/docs/posts/04-hooks.md b/docs/main-concepts/04-hooks.md similarity index 100% rename from docs/posts/04-hooks.md rename to docs/main-concepts/04-hooks.md diff --git a/docs/posts/05-context-api.md b/docs/main-concepts/05-context-api.md similarity index 100% rename from docs/posts/05-context-api.md rename to docs/main-concepts/05-context-api.md diff --git a/docs/posts/06-subscription-api.md b/docs/main-concepts/06-subscription-api.md similarity index 100% rename from docs/posts/06-subscription-api.md rename to docs/main-concepts/06-subscription-api.md diff --git a/docs/posts/07-state-management.md b/docs/main-concepts/07-state-management.md similarity index 100% rename from docs/posts/07-state-management.md rename to docs/main-concepts/07-state-management.md diff --git a/docs/posts/09-interactivity.md b/docs/main-concepts/09-interactivity.md similarity index 100% rename from docs/posts/09-interactivity.md rename to docs/main-concepts/09-interactivity.md diff --git a/docs/posts/10-concurrent-mode.md b/docs/main-concepts/10-concurrent-mode.md similarity index 100% rename from docs/posts/10-concurrent-mode.md rename to docs/main-concepts/10-concurrent-mode.md diff --git a/docs/posts/11-arena-memo.md b/docs/main-concepts/11-arena-memo.md similarity index 100% rename from docs/posts/11-arena-memo.md rename to docs/main-concepts/11-arena-memo.md diff --git a/docs/posts/01-hello-world.md b/docs/main-concepts/9901-hello-world.md similarity index 100% rename from docs/posts/01-hello-world.md rename to docs/main-concepts/9901-hello-world.md diff --git a/docs/posts/00-index.md b/docs/posts/00-index.md deleted file mode 100644 index e69466468..000000000 --- a/docs/posts/00-index.md +++ /dev/null @@ -1,37 +0,0 @@ -# Dioxus Chapter 0 - Intro + Index - - - -## Guides ------------------- -| Chapter | Description | -| ------------------ | ------------------------------------------ | -| 1-hello-world | Intro to Dioxus | -| 2-utilities | Tools to make writing apps easier | -| 3-vnode-macros | VNodes and the html! macro | -| 4-hooks | Renderer + event integration using web_sys | -| 5-context-api | Virtual DOM, patching/diffing | -| 6-subscription API | Standard bundle of useful hooks | -| 7-hello-world | Html + functional_component macro | -| 8-hello-world | Blessed state management solutions | -| 9-hello-world | Renderer + event integration using web_sys | -| 10-hello-world | Renderer + event integration using web_sys | - -## Development ------------------- -| Package | Use | -| ------- | ------------------------------------------------ | -| full | Batteries-included entrypoint with feature flags | -| core | Virtual DOM, diffing, patching, and events | -| hooks | Standard hooks | -| macro | Html + functional_component macro | -| web | Renderer + event integration using web_sys | -| live | Dedicated isomorphic framework | -| recoil | Data-flow-graph state management | -| redux | Reducer-style state management | -| bearly | Simple and idiomatic state management | - -## Books ---------------- -Book of patterns - diff --git a/docs/posts/02-utilites.md b/docs/posts/02-utilites.md deleted file mode 100644 index f23c4e05a..000000000 --- a/docs/posts/02-utilites.md +++ /dev/null @@ -1,52 +0,0 @@ -# Utilities - -There are a few macros and utility functions that make life easier when writing Dioxus components. - -## The `functional_component` procedural macro - -The `functional_component` proc macro allows you to inline props into the generic parameter of the component's context. This is useful When writing "pure" components, or when you don't want the extra clutter of structs, derives, and burden of naming things. - -This macro allows allows a classic struct definition to be embedded directly into the function arguments. The props are automatically pulled from the context and destructured into the function's body, saving an extra step. - -```rust -// Inlines and destructure props *automatically* -#[functional_component] -fn Example(cx: Context, name: &str, pending: bool, count: i32 ) -> VNode { - html! { -
-

"Hello, {name}!"

-

"Status: {pending}!"

-

"Count {count}!"

-
- } -} -``` - -becomes this: - -```rust -#[derive(Debug, Properties, PartialEq)] -struct ExampleProps { - name: String - pending: bool - count: i32 -}; - -fn Example(cx: &mut Context) -> VNode { - let ExampleProps { - name, pending, count - } = cx.props; - - rsx! { -
-

"Hello, {name}!"

-

"Status: {pending}!"

-

"Count {count}!"

-
- } -} -``` - -## The rsx! macro - -The rsx! macacro is similar to the html! macro in other libraries, but with a few add-ons to make it fun and easy to work with. We'll cover the rsx macro more in depth in the [vnode-macro](3-vnode-macros.md) chapter. diff --git a/docs/posts/03-vnode-macros.md b/docs/posts/03-vnode-macros.md deleted file mode 100644 index daf5c4646..000000000 --- a/docs/posts/03-vnode-macros.md +++ /dev/null @@ -1,145 +0,0 @@ -# VNode Macros - -Dioxus comes preloaded with two macros for creating VNodes. - -## html! macro - -The html! macro supports a limited subset of the html standard. This macro will happily accept a copy-paste from something like tailwind builder. However, writing HTML by hand is a bit tedious - IDE tools for Rust don't support linting/autocomplete/syntax highlighting. RSX is much more natural for Rust programs and _does_ integrate well with Rust IDE tools. - -There is also limited support for dynamic handlers, but it will function similarly to JSX. - -You'll want to write RSX where you can, and in a future release we'll have a tool that automatically converts HTML to RSX. - -```rust -#[fc] -fn Example(cx: Context, name: &str, pending: bool, count: i32 ) -> VNode { - cx.render(html! { -
-

"Hello, {name}!"

-

"Status: {pending}!"

-

"Count {count}!"

-
- }) -} -``` - -## rsx! macro - -The rsx! macro is a VNode builder macro designed especially for Rust programs. Writing these should feel very natural, much like assembling a struct. VSCode also supports these with code folding, bracket-tabbing, bracket highlighting, and section selecting. - -The Dioxus VSCode extension will eventually provide a macro to convert a selection of html! template and turn it into rsx!, so you'll never need to transcribe templates by hand. - -It's also a bit easier on the eyes 🙂. - -```rust -#[fc] -fn Example(cx: Context, name: &str, pending: bool, count: i32 ) -> VNode { - cx.render(rsx! { - div { - p {"Hello, {name}!"} - p {"Status: {pending}!"} - p {"Count {count}!"} - } - }) -} - -``` - -Each element takes a comma-separated list of expressions to build the node. Roughly, here's how they work: - -- `name: value` sets the property on this element. -- `"text"` adds a new text element -- `tag {}` adds a new child element -- `CustomTag {}` adds a new child component -- `{expr}` pastes the `expr` tokens literally. They must be IntoCtx to work properly - -Commas are entirely optional, but might be useful to delineate between elements and attributes. - -The `render` function provides an **extremely efficient** allocator for VNodes and text, so try not to use the `format!` macro in your components. Rust's default `ToString` methods pass through the global allocator, but all text in components is allocated inside a manually-managed Bump arena. - -```rust -static Example: FC<()> = |cx| { - - let text = "example"; - - cx.render(rsx!{ - div { - h1 { "Example" }, - - // fstring interpolation - "{text}" - - p { - // Attributes - tag: "type", - - // Anything that implements display can be an attribute - abc: 123, - enabled: true, - - // attributes also supports interpolation - // `class` is not a restricted keyword unlike JS and ClassName - class: "big small wide short {text}", - - // bool-based classnames - classes: [("big", true), ("small", false)] - - // Bool-based props - // *must* be in the tuple form, cannot enter as a variable - tag: ("type", false) - - tag: {"these tokens are placed directly"} - - // Children - a { "abcder" }, - - // Children with attributes - h2 { "hello", class: "abc-123" }, - - // Child components - CustomComponent { a: 123, b: 456, key: "1" }, - - // Child components with paths - crate::components::CustomComponent { a: 123, b: 456, key: "1" }, - - // Iterators - { 0..3.map(|i| rsx!{ h1 {"{:i}"} }) }, - - // More rsx!, or even html! - { rsx! { div { } } }, - { html! {
} }, - - // Matching - // Requires rendering the nodes first. - // rsx! is lazy, and the underlying closures cannot have the same type - // Rendering produces the VNode type - {match rand::gen_range::(1..3) { - 1 => rsx!(in cx, h1 { "big" }) - 2 => rsx!(in cx, h2 { "medium" }) - _ => rsx!(in cx, h3 { "small" }) - }} - - // Optionals - {true.and_then(|f| rsx!{ h1 {"Conditional Rendering"} })} - - // Bool options - {(rsx!{ h1 {"Conditional Rendering"}, true)} - - // Child nodes - // Returns &[VNode] - {cx.children()} - - // Duplicating nodes - // Clones the nodes by reference, so they are literally identical - {{ - let node = rsx!(in cx, h1{ "TopNode" }); - (0..10).map(|_| node.clone()) - }} - - // Any expression that is `IntoVNode` - {expr} - } - } - }) -} -``` diff --git a/packages/core/Cargo.toml b/packages/core/Cargo.toml index 6263f22b4..3b448e21b 100644 --- a/packages/core/Cargo.toml +++ b/packages/core/Cargo.toml @@ -34,15 +34,16 @@ longest-increasing-subsequence = "0.1.0" # internall used log = "0.4" -# Serialize the Edits for use in Webview/Liveview instances -serde = { version="1", features=["derive"], optional=true } +# # Serialize the Edits for use in Webview/Liveview instances +# serde = { version="1", features=["derive"], optional=true } smallvec = "1.6.1" +slotmap = "1.0.3" futures = "0.3.15" [features] default = [] -serialize = ["serde", "generational-arena/serde"] +serialize = ["generational-arena/serde"]