diff --git a/docs-src/0.6/src/SUMMARY.md b/docs-src/0.6/src/SUMMARY.md index 8f1389f71..a51fe9e24 100644 --- a/docs-src/0.6/src/SUMMARY.md +++ b/docs-src/0.6/src/SUMMARY.md @@ -27,6 +27,7 @@ - [Managing State](essentials/state/index.md) - [Async](essentials/async/index.md) - [Breaking Out](essentials/breaking/index.md) + - [Error Handling](essentials/error_handling/index.md) --- @@ -65,7 +66,6 @@ - [Static Site Generation](guides/fullstack/static_site_generation.md) - [Publishing](cookbook/publishing.md) - [Anti-patterns](cookbook/antipatterns.md) - - [Error Handling](cookbook/error_handling.md) - [Integrations](cookbook/integrations/index.md) - [Logging](cookbook/integrations/logging.md) - [Internationalization](cookbook/integrations/internationalization.md) diff --git a/docs-src/0.6/src/cookbook/error_handling.md b/docs-src/0.6/src/cookbook/error_handling.md deleted file mode 100644 index 6c2d0ef1f..000000000 --- a/docs-src/0.6/src/cookbook/error_handling.md +++ /dev/null @@ -1,79 +0,0 @@ -# Error handling - -A selling point of Rust for web development is the reliability of always knowing where errors can occur and being forced to handle them - -However, we haven't talked about error handling at all in this guide! In this chapter, we'll cover some strategies in handling errors to ensure your app never crashes. - - - -## The simplest – returning None - -Astute observers might have noticed that `Element` is actually a type alias for `Option`. You don't need to know what a `VNode` is, but it's important to recognize that we could actually return nothing at all: - -```rust -{{#include src/doc_examples/error_handling.rs:none}} -``` - -This lets us add in some syntactic sugar for operations we think *shouldn't* fail, but we're still not confident enough to "unwrap" on. - -> The nature of `Option` might change in the future as the `try` trait gets upgraded. - -```rust -{{#include src/doc_examples/error_handling.rs:try_hook}} -``` - -## Early return on result - -Because Rust can't accept both Options and Results with the existing try infrastructure, you'll need to manually handle Results. This can be done by converting them into Options or by explicitly handling them. If you choose to convert your Result into an Option and bubble it with a `?`, keep in mind that if you do hit an error you will lose error information and nothing will be rendered for that component. - -```rust -{{#include src/doc_examples/error_handling.rs:try_result_hook}} -``` - -Notice that while hooks in Dioxus do not like being called in conditionals or loops, they *are* okay with early returns. Returning an error state early is a completely valid way of handling errors. - - -## Match results - -The next "best" way of handling errors in Dioxus is to match on the error locally. This is the most robust way of handling errors, but it doesn't scale to architectures beyond a single component. - -To do this, we simply have an error state built into our component: - -```rust -{{#include src/doc_examples/error_handling.rs:use_error}} -``` - -Whenever we perform an action that generates an error, we'll set that error state. We can then match on the error in a number of ways (early return, return Element, etc). - - -```rust -{{#include src/doc_examples/error_handling.rs:match_error}} -``` - -## Passing error states through components - -If you're dealing with a handful of components with minimal nesting, you can just pass the error handle into child components. - -```rust -{{#include src/doc_examples/error_handling.rs:match_error_children}} -``` - -Much like before, our child components can manually set the error during their own actions. The advantage to this pattern is that we can easily isolate error states to a few components at a time, making our app more predictable and robust. - -## Throwing errors - -Dioxus provides a much easier way to handle errors: throwing them. Throwing errors combines the best parts of an error state and early return: you can easily throw and error with `?`, but you keep information about the error so that you can handle it in a parent component. - -You can call `throw` on any `Result` type that implements `Debug` to turn it into an error state and then use `?` to return early if you do hit an error. You can capture the error state with an `ErrorBoundary` component that will render the a different component if an error is thrown in any of its children. - -```rust -{{#include src/doc_examples/error_handling.rs:throw_error}} -``` - -You can even nest `ErrorBoundary` components to capture errors at different levels of your app. - -```rust -{{#include src/doc_examples/error_handling.rs:nested_throw}} -``` - -This pattern is particularly helpful whenever your code generates a non-recoverable error. You can gracefully capture these "global" error states without panicking or handling state for each error yourself. diff --git a/docs-src/0.6/src/cookbook/index.md b/docs-src/0.6/src/cookbook/index.md index a01e51523..44084491f 100644 --- a/docs-src/0.6/src/cookbook/index.md +++ b/docs-src/0.6/src/cookbook/index.md @@ -6,7 +6,6 @@ There are a few different sections in the cookbook: - [Publishing](publishing.md) will teach you how to present your app in a variety of delicious forms. - Explore the [Anti-patterns](antipatterns.md) section to discover what ingredients to avoid when preparing your application. -- Within [Error Handling](error_handling.md), we'll master the fine art of managing spoiled ingredients in Dioxus. - Take a culinary journey through [State management](state/index.md), where we'll explore the world of handling local, global, and external state in Dioxus. - [Integrations](integrations/index.md) will guide you how to seamlessly blend external libraries into your Dioxus culinary creations. - [Testing](testing.md) explains how to examine the unique flavor of Dioxus-specific features, like components. diff --git a/docs-src/0.6/src/essentials/error_handling/index.md b/docs-src/0.6/src/essentials/error_handling/index.md new file mode 100644 index 000000000..caa761a61 --- /dev/null +++ b/docs-src/0.6/src/essentials/error_handling/index.md @@ -0,0 +1,55 @@ +# Error handling + +A selling point of Rust for web development is the reliability of always knowing where errors can occur and being forced to handle them. Dioxus provides ErrorBoundarys to help you handle errors in a declarative way. This guide will teach you how to use ErrorBoundaries and other error handling strategies in Dioxus. + +## Returning Errors from Components + +Astute observers might have noticed that `Element` is actually a type alias for `Result`. The `RenderError` type can be created from an error type that implements `Error`. You can use `?` to bubble up any errors you encounter while rendering to the nearest error boundary: + +```rust +{{#include src/doc_examples/error_handling.rs:throw_error}} +``` + +## Capturing errors with ErrorBoundaries + +When you return an error from a component, it gets sent to the nearest error boundary. That error boundary can then handle the error and render a fallback UI with the handle_error closure: + +```rust +{{#include src/doc_examples/error_handling.rs:capture_error}} +``` + +## Throwing Errors from Event Handlers + +In addition to components, you can throw errors from event handlers. If you throw an error from an event handler, it will bubble up to the nearest error boundary just like a component: + +```rust +{{#include src/doc_examples/error_handling.rs:throw_error_event_handler}} +``` + +## Adding context to errors + +You can add additional context to your errors with the [`Context`](https://docs.rs/dioxus/0.6/dioxus/prelude/trait.Context.html) trait. Calling `context` on a `Result` will add the context to the error variant of the `Result`: + +```rust, no_run +{{#include src/doc_examples/error_handling.rs:add_context}} +``` + +If you need some custom UI for the error message, you can call `show` on a result to attach an Element to the error variant. The parent error boundary can choose to render this element instead of the default error message: + +```rust, no_run +{{#include src/doc_examples/error_handling.rs:show}} +``` + +## Local Error Handling + +If you need more fine-grained control over error states, you can store errors in reactive hooks and use them just like any other value. For example, if you need to show a phone number validation error, you can store the error in a memo and show it below the input field if it is invalid: + +```rust, no_run +{{#include src/doc_examples/error_handling.rs:phone_number_validation}} +``` + +```inject-dioxus +DemoFrame { + error_handling::PhoneNumberValidation {} +} +``` diff --git a/docs-src/0.6/src/essentials/index.md b/docs-src/0.6/src/essentials/index.md index 74c7621c7..eb2ab0e18 100644 --- a/docs-src/0.6/src/essentials/index.md +++ b/docs-src/0.6/src/essentials/index.md @@ -11,3 +11,5 @@ This section will guide you through key concepts in Dioxus: - [Breaking Out](breaking/index.md) will teach you how to break out of Dioxus' rendering model to run JavaScript or interact with the DOM directly with `web-sys`. - [Async](async/index.md) will teach you how to integrate async tasks with Dioxus and how to handle loading states while waiting for async tasks to finish. + +- [Error Handling](error_handling/index.md) will teach you how to throw and handle errors in Dioxus. diff --git a/docs-src/0.6/src/reference/hooks.md b/docs-src/0.6/src/reference/hooks.md index a61f4fb22..369d92960 100644 --- a/docs-src/0.6/src/reference/hooks.md +++ b/docs-src/0.6/src/reference/hooks.md @@ -68,7 +68,7 @@ This is only possible because the two hooks are always called in the same order, 1. Hooks may be only used in components or other hooks (we'll get to that later). 2. On every call to a component function. -3. The same hooks must be called (except in the case of early returns, as explained later in the [Error Handling chapter](../cookbook/error_handling.md)). +3. The same hooks must be called (except in the case of early returns, as explained later in the [Error Handling chapter](../essentials/error_handling/index.md)). 4. In the same order. 5. Hook names should start with `use_` so you don't accidentally confuse them with regular functions (`use_signal()`, `use_signal()`, `use_resource()`, etc...). diff --git a/packages/docs-router/src/doc_examples/error_handling.rs b/packages/docs-router/src/doc_examples/error_handling.rs index 4f2ba4a52..6cf03598f 100644 --- a/packages/docs-router/src/doc_examples/error_handling.rs +++ b/packages/docs-router/src/doc_examples/error_handling.rs @@ -1,151 +1,216 @@ use dioxus::prelude::*; -mod handle_none { - use super::*; - // ANCHOR: none - fn App() -> Element { - rsx! {} - } - // ANCHOR_END: none -} - -mod try_hook { +mod throw_error { use super::*; - // ANCHOR: try_hook - fn App() -> Element { - // immediately return "None" - let name = use_hook(|| dioxus::Result::Ok("hi"))?; + // ANCHOR: throw_error + #[component] + fn ThrowsError() -> Element { + // You can return any type that implements `Error` + let number: i32 = use_hook(|| "1.234").parse()?; todo!() } - // ANCHOR_END: try_hook + // ANCHOR_END: throw_error } -mod try_result_hook { +mod capture_error { use super::*; - // ANCHOR: try_result_hook - fn App() -> Element { - // Convert Result to Option - let name: i32 = use_hook(|| "1.234").parse().context("Failed to parse")?; - - // Early return - let count = use_hook(|| "1.234"); - let val: i32 = match count.parse() { - Ok(val) => val, - Err(err) => return rsx! { "Parsing failed" }, - }; - - todo!() + // ANCHOR: capture_error + #[component] + fn Parent() -> Element { + rsx! { + ErrorBoundary { + // The error boundary accepts a closure that will be rendered when an error is thrown in any + // of the children + handle_error: |_| { + rsx! { "Oops, we encountered an error. Please report this to the developer of this application" } + }, + ThrowsError {} + } + } } - // ANCHOR_END: try_result_hook -} + // ANCHOR_END: capture_error -mod match_error { - use super::*; - // ANCHOR: match_error - fn Commandline() -> Element { - // ANCHOR: use_error - let mut error = use_signal(|| None); - // ANCHOR_END: use_error - - match error() { - Some(error) => rsx! { - h1 { "An error occurred" } - }, - None => rsx! { - input { oninput: move |_| error.set(Some("bad thing happened!")) } - }, - } + #[component] + fn ThrowsError() -> Element { + let number: i32 = use_hook(|| "1...234").parse()?; + + todo!() } - // ANCHOR_END: match_error } -mod match_error_children { +mod throw_error_event_handler { use super::*; - // ANCHOR: match_error_children - fn Commandline() -> Element { - let error = use_signal(|| None); + // ANCHOR: throw_error_event_handler + #[component] + fn ThrowsError() -> Element { + rsx! { + button { + onclick: move |_| { + // Event handlers can return errors just like components + let number: i32 = "1...234".parse()?; - if let Some(error) = error() { - return rsx! { "An error occurred" }; - } + tracing::info!("Parsed number: {number}"); - rsx! { - Child { error } - Child { error } - Child { error } - Child { error } + Ok(()) + }, + "Throw error" + } } } + // ANCHOR_END: throw_error_event_handler +} +mod add_context { + use super::*; + // ANCHOR: add_context #[component] - fn Child(error: Signal>) -> Element { - rsx! { - input { oninput: move |_| error.set(Some("bad thing happened!")) } - } + fn ThrowsError() -> Element { + // You can call the context method on results to add more information to the error + let number: i32 = use_hook(|| "1.234") + .parse() + .context("Failed to parse name")?; + + todo!() } - // ANCHOR_END: match_error_children + // ANCHOR_END: add_context } -mod throw_error { +mod show { use super::*; - // ANCHOR: throw_error + // ANCHOR: show + #[component] fn Parent() -> Element { rsx! { ErrorBoundary { - handle_error: |ctx: ErrorContext| { - let error = &ctx.errors()[0]; - rsx! { - "Oops, we encountered an error. Please report {error} to the developer of this application" + // The error boundary accepts a closure that will be rendered when an error is thrown in any + // of the children + handle_error: |error: ErrorContext| { + if let Some(error_ui) = error.show() { + rsx! { + {error_ui} + } + } else { + rsx! { + div { + "Oops, we encountered an error. Please report this to the developer of this application" + } + } } }, ThrowsError {} } } } + // ANCHOR_END: show + #[component] fn ThrowsError() -> Element { - let name: i32 = use_hook(|| "1.234").parse().context("Failed to parse")?; + let number: i32 = use_hook(|| "1...234").parse().show(|error| { + rsx! { + div { + background_color: "red", + color: "white", + "Error parsing number: {error}" + } + } + })?; todo!() } - // ANCHOR_END: throw_error } -mod nested_throw { + +pub use phone_number_validation::PhoneNumberValidation; + +mod phone_number_validation { use super::*; - // ANCHOR: nested_throw - fn App() -> Element { - rsx! { - ErrorBoundary { - handle_error: |ctx: ErrorContext| { - let error = &ctx.errors()[0]; - rsx! { - "Hmm, something went wrong. Please report {error} to the developer of this application" - } - }, - Parent {} + use std::convert::TryInto; + use std::str::FromStr; + + #[derive(Clone, Copy, PartialEq, Eq, Hash)] + struct PhoneNumber { + country_code: Option, + sections: [u32; 3], + } + + impl std::fmt::Display for PhoneNumber { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + if let Some(country_code) = self.country_code { + write!(f, "+{country_code} ")?; } + let [area_code, exchange, subscriber] = &self.sections; + write!(f, "{}-{}-{}", area_code, exchange, subscriber) } } - fn Parent() -> Element { - rsx! { - ErrorBoundary { - handle_error: |ctx: ErrorContext| { - let error = &ctx.errors()[0]; - rsx! { - "The child component encountered an error: {error}" - } - }, - ThrowsError {} + impl FromStr for PhoneNumber { + type Err = String; + + fn from_str(phone_number: &str) -> Result { + let phone_number = phone_number.trim(); + let mut sections = phone_number.split('-'); + let country_code = if phone_number.starts_with('+') { + match sections.next() { + Some(country_code) => Some( + country_code + .parse::() + .map_err(|_| "Invalid country code".to_string())?, + ), + None => return Err("Expected country code after +".to_string()), + } + } else { + None + }; + + let sections = sections + .map(|s| s.parse::()) + .collect::, _>>() + .map_err(|_| "failed to parse phone number")?; + if sections.len() != 3 { + return Err("Expected 3 numbers after the country code".to_string()); } + let mut sections_array = [0; 3]; + sections_array + .iter_mut() + .zip(sections) + .for_each(|(a, b)| *a = b); + + Ok(PhoneNumber { + country_code, + sections: sections_array, + }) } } - fn ThrowsError() -> Element { - let name: i32 = use_hook(|| "1.234").parse().context("Failed to parse")?; + // ANCHOR: phone_number_validation + #[component] + pub fn PhoneNumberValidation() -> Element { + let mut phone_number = use_signal(|| String::new()); + let parsed_phone_number = use_memo(move || phone_number().parse::()); - todo!() + rsx! { + input { + class: "border border-gray-300 rounded-md p-2 mb-4", + placeholder: "Phone number", + value: "{phone_number}", + oninput: move |e| { + phone_number.set(e.value()); + }, + } + + match parsed_phone_number() { + Ok(phone_number) => rsx! { + div { + "Parsed phone number: {phone_number}" + } + }, + Err(error) => rsx! { + div { + "Phone number is invalid: {error}" + } + } + } + } } - // ANCHOR_END: nested_throw + // ANCHOR_END: phone_number_validation } diff --git a/packages/docs-router/src/doc_examples/mod.rs b/packages/docs-router/src/doc_examples/mod.rs index 6624d154f..38dbd6c4b 100644 --- a/packages/docs-router/src/doc_examples/mod.rs +++ b/packages/docs-router/src/doc_examples/mod.rs @@ -76,6 +76,8 @@ pub mod conditional_rendering; #[cfg(not(feature = "doc_test"))] pub mod dangerous_inner_html; #[cfg(not(feature = "doc_test"))] +pub mod error_handling; +#[cfg(not(feature = "doc_test"))] pub mod event_click; #[cfg(not(feature = "doc_test"))] pub mod event_prevent_default; diff --git a/packages/docs-router/src/docs.rs b/packages/docs-router/src/docs.rs index d5d750914..b5edfdb58 100644 --- a/packages/docs-router/src/docs.rs +++ b/packages/docs-router/src/docs.rs @@ -1,8 +1,7 @@ +use crate::desktop_dependencies::*; use crate::doc_examples::*; use dioxus::prelude::*; -use mdbook_shared::MdBook; use std::hash::Hash; -use crate::desktop_dependencies::*; pub mod router_03; pub mod router_04; @@ -94,8 +93,7 @@ fn CodeBlock(contents: String, name: Option) -> Element { } } - -pub(crate) static Copy: Component<()> = |cx| { +pub(crate) static Copy: Component<()> = |_| { rsx!( svg { width: "24", diff --git a/packages/docs-router/src/lib.rs b/packages/docs-router/src/lib.rs index 125c70eee..a7ddd9b2f 100644 --- a/packages/docs-router/src/lib.rs +++ b/packages/docs-router/src/lib.rs @@ -1,3 +1,3 @@ -pub mod docs; -pub mod doc_examples; pub mod desktop_dependencies; +pub mod doc_examples; +pub mod docs; diff --git a/packages/docsite/src/docs.rs b/packages/docsite/src/docs.rs index 45757b25a..593d34e44 100644 --- a/packages/docsite/src/docs.rs +++ b/packages/docsite/src/docs.rs @@ -1,9 +1,9 @@ +use crate::Route; use dioxus::prelude::*; use mdbook_shared::MdBook; use std::hash::Hash; -use crate::Route; -pub use dioxus_docs_router::{docs::*, doc_examples::*}; +pub use dioxus_docs_router::{doc_examples::*, docs::*}; pub enum CurrentDocsVersion { V06(router_06::BookRoute), diff --git a/packages/include_mdbook/packages/mdbook-gen/src/rsx.rs b/packages/include_mdbook/packages/mdbook-gen/src/rsx.rs index e15bf1e68..7d4c82980 100644 --- a/packages/include_mdbook/packages/mdbook-gen/src/rsx.rs +++ b/packages/include_mdbook/packages/mdbook-gen/src/rsx.rs @@ -651,7 +651,7 @@ fn transform_code_block( return Ok(code_contents); } - let mut segments = code_contents.split("{{#"); + let segments = code_contents.split("{{#"); let mut output = String::new(); for segment in segments { if let Some((plugin, after)) = segment.split_once("}}") { diff --git a/packages/playground/playground/src/components/icons.rs b/packages/playground/playground/src/components/icons.rs index 52915c74b..a5feaf574 100644 --- a/packages/playground/playground/src/components/icons.rs +++ b/packages/playground/playground/src/components/icons.rs @@ -19,8 +19,8 @@ pub fn MenuIcon() -> Element { rsx! { svg { xmlns: "http://www.w3.org/2000/svg", - height: "24px", - "viewBox": "0 -960 960 960", + height: "24px", + "viewBox": "0 -960 960 960", fill: "currentColor", path { d: "M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z" } } diff --git a/packages/playground/playground/src/lib.rs b/packages/playground/playground/src/lib.rs index 7bcd0ea1f..b67e9f045 100644 --- a/packages/playground/playground/src/lib.rs +++ b/packages/playground/playground/src/lib.rs @@ -178,7 +178,7 @@ pub fn Playground( }, h3 { {example.path.clone()} } p { {example.description.clone()} } - } + } } } components::Panes {