From cd5b8a520c769155f9cc1a627dc01d1cdebb0fbd Mon Sep 17 00:00:00 2001 From: WorldSEnder Date: Wed, 20 Apr 2022 13:41:42 +0200 Subject: [PATCH] Improve grammar and paragraph structure in documentation (#2620) * Read through the docs and correct spelling and grammar * Run prettier * Apply review suggestions Co-authored-by: Muhammad Hamza * adjust translation messages Co-authored-by: Muhammad Hamza --- examples/keyed_list/src/main.rs | 30 ++++--- website/docs/concepts/agents.mdx | 2 +- .../concepts/basic-web-technologies/css.mdx | 15 ++-- .../concepts/basic-web-technologies/html.mdx | 85 +++++++++---------- .../concepts/basic-web-technologies/js.mdx | 19 ++--- .../wasm-bindgen.mdx} | 4 +- .../web-sys.mdx | 6 +- .../function-components/callbacks.mdx | 14 +-- .../concepts/function-components/children.mdx | 7 +- .../hooks/custom-hooks.mdx | 29 +++---- .../hooks/introduction.mdx | 12 +-- .../hooks/use-callback.mdx | 2 +- .../function-components/hooks/use-context.mdx | 2 - .../function-components/hooks/use-effect.mdx | 52 ++---------- .../hooks/use-force-update.mdx | 6 +- .../function-components/hooks/use-memo.mdx | 2 +- .../hooks/use-node-ref.mdx | 6 +- .../function-components/hooks/use-reducer.mdx | 4 +- .../function-components/hooks/use-state.mdx | 2 +- .../function-components/introduction.mdx | 45 +++++----- .../function-components/node-refs.mdx | 12 ++- .../function-components/properties.mdx | 32 +++---- .../function-components/pure-components.mdx | 23 ++--- .../concepts/function-components/state.mdx | 20 ++--- website/docs/concepts/html/lists.mdx | 27 +++--- .../getting-started/build-a-sample-app.mdx | 5 +- website/docs/getting-started/editor-setup.mdx | 77 +++++++++-------- website/docs/getting-started/examples.mdx | 7 +- .../current.json | 28 ++---- .../current.json | 28 ++---- .../current.json | 28 ++---- website/sidebars/docs.js | 27 ++---- 32 files changed, 297 insertions(+), 361 deletions(-) rename website/docs/concepts/{wasm-bindgen/introduction.mdx => basic-web-technologies/wasm-bindgen.mdx} (99%) rename website/docs/concepts/{wasm-bindgen => basic-web-technologies}/web-sys.mdx (96%) diff --git a/examples/keyed_list/src/main.rs b/examples/keyed_list/src/main.rs index 7b87283b4..d5d6d9dae 100644 --- a/examples/keyed_list/src/main.rs +++ b/examples/keyed_list/src/main.rs @@ -1,3 +1,5 @@ +use std::cell::RefCell; + use instant::Instant; use person::PersonType; use web_sys::{HtmlElement, HtmlInputElement}; @@ -20,7 +22,6 @@ pub enum Msg { SortByAge, SortByAddress, ToggleKeyed, - Rendered(Instant), } pub struct App { @@ -29,6 +30,7 @@ pub struct App { keyed: bool, build_component_ratio: f64, delta_ref: NodeRef, + last_view: RefCell>, } impl Component for App { @@ -42,6 +44,7 @@ impl Component for App { keyed: true, build_component_ratio: 0.5, delta_ref: NodeRef::default(), + last_view: RefCell::default(), } } @@ -122,22 +125,23 @@ impl Component for App { self.keyed = !self.keyed; true } - Msg::Rendered(time_before) => { - let time_after = Instant::now(); - let elapsed_max = time_after - time_before; - log::info!("Rendering started {} ms ago.", elapsed_max.as_millis()); - if let Some(input) = self.delta_ref.cast::() { - let delta_text = - format!("The last rendering took {} ms", elapsed_max.as_millis()); - input.set_inner_text(&delta_text); - } - false - } } } + fn rendered(&mut self, _ctx: &Context, _first_render: bool) { + let time_after = Instant::now(); + let elapsed_max = time_after - self.last_view.get_mut().take().unwrap(); + log::info!("Rendering started {} ms ago.", elapsed_max.as_millis()); + let output = self.delta_ref.cast::().unwrap(); + let delta_text = format!("The last rendering took {} ms", elapsed_max.as_millis()); + output.set_inner_text(&delta_text); + } + fn view(&self, ctx: &Context) -> Html { - ctx.link().send_message(Msg::Rendered(Instant::now())); + let mut last_view = self.last_view.borrow_mut(); + if last_view.is_none() { + *last_view = Some(Instant::now()); + } html! {
diff --git a/website/docs/concepts/agents.mdx b/website/docs/concepts/agents.mdx index bf72d4295..a08a43972 100644 --- a/website/docs/concepts/agents.mdx +++ b/website/docs/concepts/agents.mdx @@ -6,7 +6,7 @@ description: "Yew's Actor System" import useBaseUrl from '@docusaurus/useBaseUrl' import ThemedImage from '@theme/ThemedImage' -Agents are a way to offload tasks to web workers or achieve inter-tab communication(WIP). +Agents are a way to offload tasks to web workers. In order for agents to run concurrently, Yew uses [web-workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers). diff --git a/website/docs/concepts/basic-web-technologies/css.mdx b/website/docs/concepts/basic-web-technologies/css.mdx index 76fff27af..d5efddc82 100644 --- a/website/docs/concepts/basic-web-technologies/css.mdx +++ b/website/docs/concepts/basic-web-technologies/css.mdx @@ -7,16 +7,12 @@ comment: 'Keep this file as short and simple as possible. Its purpose is to ease import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -> Yew mostly operates on the idea of keeping everything that a reusable piece of -> UI may need, in one place - rust files. But also seeks to stay close to the -> original look of the technology. - -Yew does not provide css in rs solutions natively, but helps with css by providing -programmatic ways to interact with css classes. +Yew does not natively provide a css in rust solution, but helps with styling by providing +programmatic ways to interact with the html `class` attribute. ## Classes -The struct `Classes` simplifies use of HTML classes: +The `classes!` macro and associated `Classes` struct simplify the use of HTML classes: @@ -25,7 +21,7 @@ The struct `Classes` simplifies use of HTML classes: use yew::{classes, html}; html! { -
+
}; ``` @@ -91,7 +87,8 @@ We will expand upon this concept in [more CSS](../../more/css). ## Inline Styles -Currently Yew does not provide any help with inline styles natively: +Currently Yew does not provide any special help with inline styles specified via the `styles` attribute, +but you can use it like any other html attribute: ```rust use yew::{classes, html}; diff --git a/website/docs/concepts/basic-web-technologies/html.mdx b/website/docs/concepts/basic-web-technologies/html.mdx index 33b56b6c2..8861c3f5c 100644 --- a/website/docs/concepts/basic-web-technologies/html.mdx +++ b/website/docs/concepts/basic-web-technologies/html.mdx @@ -7,82 +7,73 @@ comment: 'Keep this file as short and simple as possible. Its purpose is to ease import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -> Yew mostly operates on the idea of keeping everything that a reusable piece of -> UI may need, in one place - rust files. But also seeks to stay close to the -> original look of the technology. - -For HTML we achieve this by providing the `html!` macro: +You can write expressions resembling HTML with the `html!` macro. Behind the scenes Yew turns +it into rust code representing the DOM to generate. ```rust use yew::prelude::*; -let my_header: Html = html!{Girl in a jacket}; +let my_header: Html = html! { + Girl in a jacket +}; ``` -`html!` macro allows you to write html generation as if it was in a `.html` file and then behind the scenes by yew gets turned into internal builder patterns that generate all DOM nodes. - -As it is part of rust code it provides a easy way to switch from html to rust by applying curly brackets: +Similar to format expressions, there is an easy way to embed values from the surrounding +context into the html by applying curly brackets: ```rust use yew::prelude::*; let header_text = "Hello world".to_string(); -let header_html: Html = html!{

{header_text}

}; +let header_html: Html = html! { +

{header_text}

+}; let count: usize = 5; -let counter_html: Html = html!{

{"My age is: "}{count}

}; +let counter_html: Html = html! { +

{"My age is: "}{count}

+}; -let combined_html: Html = html!{
{header_html}{counter_html}
}; +let combined_html: Html = html! { +
{header_html}{counter_html}
+}; ``` -One rule major rule comes with use of `html!` - you can only return 1 wrapping node: +One rule major rule comes with use of `html!` - you can only return 1 wrapping node. +To render a list of multiple elements, `html!` allows fragments. Fragments are tags +without a name, that produce no html element by themselves. + + +```rust , compile_fail +use yew::html; + +// error: only one root html element allowed +html! { + +
+

+ +}; +``` + + ```rust use yew::html; -html! { -
-
-

-
-}; - -``` - - - - - -```rust, compile_fail -use yew::html; - -// error: only one root html element allowed - -html! { -
-

-}; - -``` - - - - -To help with this rule and avoid `div` abuse `html!` allows fragments. Fragments are empty tags that do not provide any html result: - -```rust -use yew::html; - +// fixed: using html fragments html! { <>

}; - ``` + + + We will introduce Yew and HTML further in depth in [more HTML](concepts/html/introduction.mdx). diff --git a/website/docs/concepts/basic-web-technologies/js.mdx b/website/docs/concepts/basic-web-technologies/js.mdx index 81807eb5f..bcce54f7f 100644 --- a/website/docs/concepts/basic-web-technologies/js.mdx +++ b/website/docs/concepts/basic-web-technologies/js.mdx @@ -7,19 +7,18 @@ comment: 'Keep this file as short and simple as possible. Its purpose is to ease import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -> Yew mostly operates on the idea of keeping everything that a reusable piece of -> UI may need, in one place - rust files. But also seeks to stay close to the -> original look of the technology. +> Yew centrally operates on the idea of keeping everything that a reusable piece of +> UI may need in one place - rust files, while also keeping the underlying technology +> accessible where necessary. -Sadly as of today WebAssembly is not feature-complete for DOM interactions. This means even in Yew we sometimes rely on calling Javascript. +As of today, WebAssembly is not feature-complete for DOM interactions. This means even in Yew we +sometimes rely on calling Javascript. What follows is an overview of the involved libraries. ## wasm-bindgen -[`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) is a library and tool that allows to call javascript from rust and rust from javascript. +[`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) is a library and tool that enables calls to javascript from rust and back to rust from javascript. -We highly recommend you give a look to their [documentation](https://rustwasm.github.io/docs/wasm-bindgen/) - -We will also expand upon this concept in the [more wasm-bindgen](../wasm-bindgen). +We highly recommend you take a look at their [documentation](https://rustwasm.github.io/docs/wasm-bindgen/) and our [quick guide](./wasm-bindgen.mdx). ## web-sys @@ -51,6 +50,4 @@ let document = window() -Once again we highly recommend you give a look to their [documentation](https://rustwasm.github.io/docs/wasm-bindgen/) - -We will also expand upon this concept in the [more wasm-bindgen](../wasm-bindgen). +Once again we highly recommend you take a look at their [documentation](https://rustwasm.github.io/docs/wasm-bindgen/) and our [quick guide](./web-sys.mdx). diff --git a/website/docs/concepts/wasm-bindgen/introduction.mdx b/website/docs/concepts/basic-web-technologies/wasm-bindgen.mdx similarity index 99% rename from website/docs/concepts/wasm-bindgen/introduction.mdx rename to website/docs/concepts/basic-web-technologies/wasm-bindgen.mdx index e77e2dd95..a7d0e0f0e 100644 --- a/website/docs/concepts/wasm-bindgen/introduction.mdx +++ b/website/docs/concepts/basic-web-technologies/wasm-bindgen.mdx @@ -103,7 +103,7 @@ its own section below. _[extends section in The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-js-imports/extends.html)_ -### [`JsValue`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html) +### [`JsValue`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html) {#jsvalue} This is a representation of an object owned by JavaScript, this is a root catch-all type for `wasm-bindgen`. Any type that comes from `wasm-bindgen` is a `JsValue` and this is because JavaScript doesn't have @@ -117,7 +117,7 @@ being imported as to whether an exception (panic) will be raised if that value i _[`JsValue` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html)._ -### [`JsCast`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html) +### [`JsCast`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html) {#JsCast} Rust has a strong type system and JavaScript...doesn't 😞. In order for Rust to maintain these strong types but still be convenient the WebAssembly group came up with a pretty neat trait `JsCast`. diff --git a/website/docs/concepts/wasm-bindgen/web-sys.mdx b/website/docs/concepts/basic-web-technologies/web-sys.mdx similarity index 96% rename from website/docs/concepts/wasm-bindgen/web-sys.mdx rename to website/docs/concepts/basic-web-technologies/web-sys.mdx index 7dc6b19ae..dc2cde590 100644 --- a/website/docs/concepts/wasm-bindgen/web-sys.mdx +++ b/website/docs/concepts/basic-web-technologies/web-sys.mdx @@ -18,13 +18,13 @@ exposes some types in it's public API, you will often need to add `web-sys` as a ## Inheritance in `web-sys` -In the [Simulating inheritance section](../wasm-bindgen#simulating-inheritance) you can read how in +In the [Simulating inheritance section](./wasm-bindgen.mdx#simulating-inheritance) you can read how in general Rust provides an approach to simulate inheritance in JavaScript. This is very important in `web-sys` as understanding what methods are available on a type means understanding it's inheritance. This section is going to look at a specific element and list out it's inheritance using Rust by calling [`Deref::deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html#tymethod.deref) until -the value is [`JsValue`](../wasm-bindgen/introduction.mdx#jsvalue): +the value is [`JsValue`](./wasm-bindgen.mdx#jsvalue): ```rust use std::ops::Deref; @@ -84,7 +84,7 @@ a `Node` made by the [`html!`](concepts/html/introduction.mdx) macro. The `Node` [`web_sys::Node`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Node.html). The `NodeRef::get` method will return a `Option` value, however, most of the time in Yew you want to cast this value to a specific element so you can use it's specific methods. This casting -can be done using [`JsCast`](../wasm-bindgen#JsCast) on the `Node` value, if present, but Yew +can be done using [`JsCast`](./wasm-bindgen.mdx#JsCast) on the `Node` value, if present, but Yew provides the `NodeRef::cast` method to perform this casting for convenience and so that you don't necessarily have to include the `wasm-bindgen` dependency for the `JsCast` trait. diff --git a/website/docs/concepts/function-components/callbacks.mdx b/website/docs/concepts/function-components/callbacks.mdx index 3aa1d087c..2c3bbf4d1 100644 --- a/website/docs/concepts/function-components/callbacks.mdx +++ b/website/docs/concepts/function-components/callbacks.mdx @@ -2,10 +2,10 @@ title: 'Callbacks' --- -Callbacks used to asynchronously communicate in Yew upwards the components tree and other things like agents or DOM. -Internally their type is just `Fn` wrapped in `Rc` to allow them to be cloned. You will need to clone them often. +Callbacks are used to asynchronously communicate upwards the components tree and with other things like agents or the DOM during event handling. +Internally their type is just an `Fn` wrapped in `Rc` to allow them to be cheaply cloned. -They have an `emit` function that takes their `` types as an arguments. +They have an `emit` function if you want to call them manually. ```rust use yew::{html, Component, Context, Html, Callback}; @@ -46,7 +46,7 @@ fn App() -> Html { // web_sys::console::log_1(&greeting.into()); // if uncommented will print }); - html! {} + html! { } } ``` @@ -55,7 +55,7 @@ fn App() -> Html { Callbacks are also used to hook into DOM events. -For example here we define a callback that will be called when user clicks the button: +For example here we define a callback that will be called when the user clicks the button: ```rust use yew::{function_component, html, Html, Properties, Callback}; @@ -67,6 +67,8 @@ fn App() -> Html { // web_sys::console::log_1(&greeting.into()); // if uncommented will print }); - html! {} + html! { + + } } ``` diff --git a/website/docs/concepts/function-components/children.mdx b/website/docs/concepts/function-components/children.mdx index a23641045..05e0105aa 100644 --- a/website/docs/concepts/function-components/children.mdx +++ b/website/docs/concepts/function-components/children.mdx @@ -2,7 +2,7 @@ title: 'Children' --- -`Children` is a special prop type that allows you to take what was provided as `Html` children. +`Children` is a special prop type that allows you to recieve nested `Html` that is provided like html child elements. ```rust use yew::{function_component, html, Html, Properties, Children}; @@ -22,7 +22,7 @@ fn App() -> Html { #[derive(Properties, PartialEq)] pub struct Props { // highlight-next-line - pub children: Children, + pub children: Children, // the field name `children` is important! } #[function_component] @@ -30,11 +30,10 @@ fn HelloWorld(props: &Props) -> Html { html! {
// highlight-next-line - { for props.children.iter() } //then use like this + { for props.children.iter() } // you can forward children like this
} } - ``` ## Further reading diff --git a/website/docs/concepts/function-components/hooks/custom-hooks.mdx b/website/docs/concepts/function-components/hooks/custom-hooks.mdx index aeca9200b..0a1c2b094 100644 --- a/website/docs/concepts/function-components/hooks/custom-hooks.mdx +++ b/website/docs/concepts/function-components/hooks/custom-hooks.mdx @@ -4,7 +4,7 @@ title: 'Custom Hooks' ## Defining custom Hooks -Component's stateful logic can be extracted into usable function by creating custom Hooks +Component's stateful logic can be extracted into reusable function by creating custom Hooks. Consider that we wish to create an event listener that listens to an event on the `window` object. @@ -35,11 +35,11 @@ pub fn show_storage_changed() -> Html { There's one problem with this code: the logic can't be reused by another component. If we build another component which keeps track of the an event, -instead of copying the code we can move the logic into a custom hook. +instead of copying the code, we can move the logic into a custom hook. We'll start by creating a new function called `use_event`. The `use_` prefix denotes that a function is a hook. -This function will take an event target, a event type and a callback. +This function will take an event target, an event type and a callback. All hooks must be marked by `#[hook]` to function as as hook. ```rust @@ -58,8 +58,8 @@ where } ``` -This is a simple hook which can be created by using built-in hooks. For this example, we'll use the `use_effect_with_deps` hook, -which subscribes to the dependencies so an event listener can be recreated when hook arguments change. +This is a simple hook which can be created by composing built-in hooks. For this example, we'll use the +`use_effect_with_deps` hook, so an event listener can be recreated when the hook arguments change. ```rust use yew::prelude::*; @@ -72,28 +72,19 @@ use gloo::events::EventListener; pub fn use_event(target: &EventTarget, event_type: E, callback: F) where E: Into>, - F: Fn(&Event) + 'static, + F: Fn(Event) + 'static, { - #[derive(Clone)] + #[derive(PartialEq, Clone)] struct EventDependents { target: EventTarget, event_type: Cow<'static, str>, - callback: Rc, - } - - #[allow(clippy::vtable_address_comparisons)] - impl PartialEq for EventDependents { - fn eq(&self, rhs: &Self) -> bool { - self.target == rhs.target - && self.event_type == rhs.event_type - && Rc::ptr_eq(&self.callback, &rhs.callback) - } + callback: Callback, } let deps = EventDependents { target: target.clone(), event_type: event_type.into(), - callback: Rc::new(callback) as Rc, + callback: Callback::from(callback), }; use_effect_with_deps( @@ -105,7 +96,7 @@ where } = deps.clone(); let listener = EventListener::new(&target, event_type, move |e| { - callback(e); + callback.emit(e.clone()); }); move || { diff --git a/website/docs/concepts/function-components/hooks/introduction.mdx b/website/docs/concepts/function-components/hooks/introduction.mdx index e96ae622f..da0bad5b4 100644 --- a/website/docs/concepts/function-components/hooks/introduction.mdx +++ b/website/docs/concepts/function-components/hooks/introduction.mdx @@ -12,14 +12,14 @@ Yew comes with a few pre-defined Hooks. You can also create your own or discover ## Rules of hooks 1. A hook function name always has to start with `use_` -2. Hooks can only be used at the following locations: +2. Hooks can only be used in the following locations: - Top level of a function / hook. - - If condition inside a function / hook, given it's not already branched. - - Match condition inside a function / hook, given it's not already branched. - Blocks inside a function / hook, given it's not already branched. -3. Hooks every render must be called in the same order + - In the condition of a top level `if` expression inside a function / hook. + - In the scrutinee of a top level `match` expression inside a function / hook. +3. Hooks must be called in the same order for every render. Returning early is only allowed when using [Suspense](../../suspense.mdx) -All these rules are enforced by either compile time or run-time errors. +These rules are enforced by either compile time or run-time errors. ### Pre-defined Hooks @@ -40,7 +40,7 @@ Yew comes with the following predefined Hooks: ### Custom Hooks -There are cases where you want to define your own Hooks for reasons. Yew allows you to define your own Hooks which lets you extract your potentially stateful logic from the component into reusable functions. +There are cases where you want to define your own Hooks to encapsulate potentially stateful logic from a component into reusable functions. See the [Defining custom hooks](concepts/function-components/hooks/custom-hooks.mdx#defining-custom-hooks) section for more information. ## Further reading diff --git a/website/docs/concepts/function-components/hooks/use-callback.mdx b/website/docs/concepts/function-components/hooks/use-callback.mdx index 03645f71d..dd0c56012 100644 --- a/website/docs/concepts/function-components/hooks/use-callback.mdx +++ b/website/docs/concepts/function-components/hooks/use-callback.mdx @@ -4,7 +4,7 @@ title: 'use_callback' `use_callback` is used for obtaining an immutable reference to a memoized `Callback`. Its state persists across renders. -It will be recreated only if any of the dependencies values change. +It will be recreated only if any of the dependencies changes value. `use_callback` can be useful when passing callbacks to optimized child components that rely on PartialEq to prevent unnecessary renders. diff --git a/website/docs/concepts/function-components/hooks/use-context.mdx b/website/docs/concepts/function-components/hooks/use-context.mdx index 10c647ae4..8f411d15c 100644 --- a/website/docs/concepts/function-components/hooks/use-context.mdx +++ b/website/docs/concepts/function-components/hooks/use-context.mdx @@ -2,8 +2,6 @@ title: 'use_context' --- -[Contexts](../../contexts.mdx) will be introduced later. - `use_context` is used for consuming [contexts](../../contexts.mdx) in function components. ## Example diff --git a/website/docs/concepts/function-components/hooks/use-effect.mdx b/website/docs/concepts/function-components/hooks/use-effect.mdx index 61093ce05..d262cb9cc 100644 --- a/website/docs/concepts/function-components/hooks/use-effect.mdx +++ b/website/docs/concepts/function-components/hooks/use-effect.mdx @@ -6,7 +6,8 @@ title: 'use_effect' It takes a function which is called every time after the component's render has finished. -The input function has to return a closure - a cleanup function, which is called right before starting a new render. +The input function has to return a closure - a cleanup function, which is called right +before starting a new render or when the component unmounts. ## Example @@ -42,11 +43,8 @@ fn EffectExample() -> Html { `use_effect_with_deps` is a more enhanced version of [`use_effect`](#use_effect). -It takes a second argument - dependencies. - -Only when dependencies change, it calls the provided function. - -Same way with the clean-up function - it gets called only before re-calling the function from the first argument. +It takes a second argument - dependencies. The effect is only executed - and the +old effect cleaned up - when the dependencies change compared to the previous call. :::note @@ -81,9 +79,10 @@ fn HelloWorld(props: &Props) -> Html { ## Tips -### Only on first render +### Only on first render {#only-on-first-render} -Provide a empty tuple `()` as dependencies when you need to do something only on first render. +Provide a empty tuple `()` as dependencies when you need to do something only on the first render +of a component. ```rust use yew::{function_component, html, Html, use_effect_with_deps}; @@ -106,7 +105,7 @@ fn HelloWorld() -> Html { ### On destructing or last render -Use [Only on first render](#only-on-first-render) and write the code in the cleanup function. +Use [Only on first render](#only-on-first-render) but put the code in the cleanup function. It will only get called when the component is removed from view / gets destroyed. ```rust @@ -116,8 +115,7 @@ use yew::{function_component, html, Html, use_effect_with_deps}; fn HelloWorld() -> Html { use_effect_with_deps( move |_| { - // move is not needed bellow but the docs page breaks without it - move || { + || { web_sys::console::log_1(&"Noo dont kill me, ahhh!".into()); } }, @@ -126,35 +124,3 @@ fn HelloWorld() -> Html { html! { "Hello" } } ``` - -### Applying event listeners to the DOM - -Generally you can directly add the `on` + event name as just a html attribute. - -But for cases when you need to do it manually always re-apply and destroy old event listeners every render to avoid duplicate listeners in the DOM. - -Same tip applies to intervals and timeouts. - -```rust -use yew::{function_component, html, Html, use_effect_with_deps, use_node_ref}; - -#[function_component] -fn HelloWorld() -> Html { - let span_ref = use_node_ref(); - - { - let span_ref = span_ref.clone(); - use_effect_with_deps( - move |_| { - let listener = gloo::events::EventListener::new(&span_ref.cast::().unwrap(), "click", move |event| { - web_sys::console::log_1(&"I got clicked".into()); - }); - move || drop(listener) - }, - (), - ); - } - - html! {{"Hello"}} -} -``` diff --git a/website/docs/concepts/function-components/hooks/use-force-update.mdx b/website/docs/concepts/function-components/hooks/use-force-update.mdx index 01ae4a577..b1eebe885 100644 --- a/website/docs/concepts/function-components/hooks/use-force-update.mdx +++ b/website/docs/concepts/function-components/hooks/use-force-update.mdx @@ -6,11 +6,9 @@ title: 'use_force_update' Usually, this re-render is triggered automatically by the hook holding your data, for example when changing the data in a handle returned from [`use_state`](./use-state). -::: caution - +:::caution Often, using this hook means you are doing something wrong and should use one of the other hooks, -for example [`use_reducer`](./use-reducer) is a great way to track changing data. - +for example [`use_reducer`](./use-reducer) is another great way to track changing data. ::: Use this hook when wrapping an API that doesn't expose precise subscription events for fetched data. diff --git a/website/docs/concepts/function-components/hooks/use-memo.mdx b/website/docs/concepts/function-components/hooks/use-memo.mdx index be6bc4be5..6210ae226 100644 --- a/website/docs/concepts/function-components/hooks/use-memo.mdx +++ b/website/docs/concepts/function-components/hooks/use-memo.mdx @@ -4,7 +4,7 @@ title: 'use_memo' `use_memo` is used for obtaining an immutable reference to a memoized value. Its state persists across renders. -Its value will be recalculated only if any of the dependencies values change. +Its value will be recalculated only if any of the dependencies changes value. `use_memo` can be useful for keeping things in scope for the lifetime of the component, so long as you don't store a clone of the resulting `Rc` anywhere that outlives the component. diff --git a/website/docs/concepts/function-components/hooks/use-node-ref.mdx b/website/docs/concepts/function-components/hooks/use-node-ref.mdx index 5e57a9c89..aeeb4f439 100644 --- a/website/docs/concepts/function-components/hooks/use-node-ref.mdx +++ b/website/docs/concepts/function-components/hooks/use-node-ref.mdx @@ -2,7 +2,11 @@ title: 'use_node_ref' --- -`use_node_ref` is used for maintaining an easy reference to the DOM element represented as a `NodeRef`. It also persists across renders. +`use_node_ref` is used for maintaining a reference to a DOM element represented as a +[`NodeRef`](../node-refs.mdx). It also persists across renders. + +The `ref` attribute can be used to attach the `NodeRef` to an HTML element. In callbacks, +you can then get the DOM `Element` that the ref is attached to. ## Example diff --git a/website/docs/concepts/function-components/hooks/use-reducer.mdx b/website/docs/concepts/function-components/hooks/use-reducer.mdx index 53aded4ac..3cb956bb9 100644 --- a/website/docs/concepts/function-components/hooks/use-reducer.mdx +++ b/website/docs/concepts/function-components/hooks/use-reducer.mdx @@ -4,7 +4,7 @@ title: 'use_reducer' `use_reducer` is an alternative to [`use_state`](./use-state). It is used to handle more complex component's state. -It accepts an initial state function and returns a `UseReducerHandle` that dereferences to the state, +It accepts an initializer function and returns a `UseReducerHandle` that dereferences to the state, and a dispatch function. The dispatch function takes one argument of type `Action`. When called, the action and current value are passed to the reducer function which computes a new state that is returned, @@ -20,7 +20,7 @@ values from within the hooks. ::: The state object returned by the initial state function is required to -implement a `Reducible` trait which provides an `Action` type and a +implement a `Reducible` trait which defines the associated `Action` type and a reducer function. This hook will always trigger a re-render upon receiving an action. See diff --git a/website/docs/concepts/function-components/hooks/use-state.mdx b/website/docs/concepts/function-components/hooks/use-state.mdx index 63d341d92..8b6369946 100644 --- a/website/docs/concepts/function-components/hooks/use-state.mdx +++ b/website/docs/concepts/function-components/hooks/use-state.mdx @@ -19,7 +19,7 @@ values from within the hook. This hook will always trigger a re-render upon receiving a new state. See [`use_state_eq`](#use_state_eq) if you want the component to only -re-render when the state changes. +re-render when the new state compares unequal to the existing one. ## Example diff --git a/website/docs/concepts/function-components/introduction.mdx b/website/docs/concepts/function-components/introduction.mdx index bd9748153..994b6e94e 100644 --- a/website/docs/concepts/function-components/introduction.mdx +++ b/website/docs/concepts/function-components/introduction.mdx @@ -5,10 +5,11 @@ slug: /concepts/function-components Lets revisit this previous statement: -> Yew mostly operates on the idea of keeping everything that a reusable piece of -> UI may need, in one place - rust files. +> Yew centrally operates on the idea of keeping everything that a reusable piece of +> UI may need in one place - rust files. -It is only partially correct, "rust files" should be replaced with "components". +We will refine this statement, by introducing the concept that will define the logic and +presentation behaviour of an application: "components". ## What are Components? @@ -18,18 +19,21 @@ They: - Take arguments in form of [Props](./properties.mdx) - Can have their own state -- Get computed into HTML visible to the user (DOM) +- Compute pieces of HTML visible to the user (DOM) ## Two flavours of Yew Components -You are currently reading about function components - the recommended way to write components when starting with Yew. +You are currently reading about function components - the recommended way to write components +when starting with Yew and when writing simple presentation logic. -But we have to note that there is a more advanced, but less recommended way to write them - [Struct components](advanced-topics/struct-components/introduction.mdx) +There is a more advanced, but less accessible, way to write components - [Struct components](advanced-topics/struct-components/introduction.mdx). +They allow very detailed control, though you will not need that level of detail most of the time. ## Creating function components To create a function component add the `#[function_component]` attribute to a function. -Also name the function in PascalCase as it is the convention for naming components. +By convention, the function is named in PascalCase, like all components, to contrast its +use to normal html elements inside the `html!` macro. ```rust use yew::{function_component, html, Html}; @@ -39,31 +43,34 @@ fn HelloWorld() -> Html { html! { "Hello world" } } -// Then somewhere else you can use the component inside the `html!` +// Then somewhere else you can use the component inside `html!` #[function_component] fn App() -> Html { - html! {} + html! { } } ``` ## What happens to components -Yew will build a tree of these components that from the previous example would look like this: +When rendering, Yew will build a virtual tree of these components. +It will call the view function of each (function) component to compute a virtual version (VDOM) of the DOM +that you as the library user see as the `Html` type. +For the previous example this would look like this: -```md - - | - +```xhtml + + +

"Hello world"

+ + ``` -It will call those functions / function components to compute a virtual version of the DOM (VDOM) that you as the library user see as the `Html` type. - -Yew will compare current DOM with VDOM and only update the new/changed/necessary parts. - +When an update is necessary, Yew will again call the view function and reconcile the new virtual DOM with its +previous version and only propagate the new/changed/necessary parts to the actual DOM. This is what we call **rendering**. :::note -Behind the scenes `Html` type is just an alias for `VNode` - virtual node. +Behind the scenes `Html` is just an alias for `VNode` - virtual node. ::: diff --git a/website/docs/concepts/function-components/node-refs.mdx b/website/docs/concepts/function-components/node-refs.mdx index fcfe7a0e4..1a83e2942 100644 --- a/website/docs/concepts/function-components/node-refs.mdx +++ b/website/docs/concepts/function-components/node-refs.mdx @@ -3,12 +3,18 @@ title: 'Node Refs' description: 'Out-of-band DOM access' --- -The `ref` keyword can be used inside of any HTML element or component to get the DOM `Element` that -the item is attached to. This can be used to make changes to the DOM outside of the `view` lifecycle -method. +The `ref` attribute can be used to attach the `NodeRef` to an HTML element. In callbacks, +you can then get the DOM `Element` that the ref is attached to. This can be used to make +changes to the DOM outside of the `view` lifecycle method, retrieve the value of an `` +and other direct interactions with the DOM via the javascript API. This is useful for getting ahold of canvas elements, or scrolling to different sections of a page. +:::caution +Do not manually modify the DOM tree that is rendered by Yew. Treat the `NodeRef` as a read-only +access, if you are unsure. +::: + ## Example See [use_node_ref hook](./hooks/use-node-ref) diff --git a/website/docs/concepts/function-components/properties.mdx b/website/docs/concepts/function-components/properties.mdx index 345e87476..dbb64cdbf 100644 --- a/website/docs/concepts/function-components/properties.mdx +++ b/website/docs/concepts/function-components/properties.mdx @@ -12,15 +12,14 @@ Properties are often shortened as "Props". ::: -Properties are essentially component function arguments that Yew can keep watch on. -Components can have an associated properties type which describes what is passed down from the parent. +Properties are essentially component arguments that Yew can keep watch on. -Props are defined using the `Properties` trait. +A type has to implement the `Properties` trait before it can be used as the properties of a component. ## Reactivity -Yew always checks if props changed to know if the component needs to be rerendered. -This way Yew can be considered a very reactive framework as any change from the parent will always be propagated downwards +Yew checks if props have changed when reconciling the vdom during rerendering, to know if nested components needs to be rerendered. +This way Yew can be considered a very reactive framework as changes from the parent will always be propagated downwards and the view will never be out of sync from the data coming from props/state. :::tip @@ -29,14 +28,9 @@ If you have not yet completed the [tutorial](../../tutorial), try it out and tes ::: -## Memory/speed overhead of using Properties - -Internally properties are reference counted. This means that only a pointer is passed down the component tree for props. -It saves us from the cost of having to clone the entire props, which might be expensive. - ## Derive macro -Yew provides a derive macro to easily implement the `Properties` trait. +Yew provides a derive macro to easily implement the `Properties` trait on structs. Types for which you derive `Properties` must also implement `PartialEq` so Yew can do data comparison. @@ -51,7 +45,8 @@ pub struct Props { ## Use in function components -The attribute `#[function_component]` allows to optionally specify Props in the function arguments +The attribute `#[function_component]` allows to optionally receive Props in the function arguments. To supply them, +they are assigned via attributes in the `html!` macro. @@ -106,8 +101,8 @@ fn App() -> Html { ## Derive macro field attributes -When deriving `Properties`, all fields are required by default. -The following attributes allow you to give your props initial values which will be used when parent has not set them. +When deriving `Properties` all fields are required by default. +The following attributes allow you to give your props default values which will be used when parent has not set them. :::tip Attributes aren't visible in Rustdoc generated documentation. @@ -155,7 +150,8 @@ fn Case2() -> Html { Use `value` to initialize the prop value. `value` can be any expression that returns the field's type. -For example, to default a boolean prop to `true`, use the attribute `#[prop_or(true)]`. +For example, to default a boolean prop to `true`, use the attribute `#[prop_or(true)]`. The expression +is evaluated when the properties are constructed and no explicit value has been given. ```rust use yew::{function_component, html, Html, Properties}; @@ -189,6 +185,7 @@ fn Case2() -> Html { Call `function` to initialize the prop value. `function` should have the signature `FnMut() -> T` where `T` is the field type. +The function is called when no explicit value has been given for that attribute. ```rust use yew::{function_component, html, Html, Properties}; @@ -225,6 +222,11 @@ fn Case2() -> Html { +## Memory/speed overhead of using Properties + +Internally properties are reference counted. This means that only a shared pointer is passed down the component tree for props. +It saves us from the cost of having to clone the entire props, which might be expensive. + ## Props macro The `yew::props!` macro allows you to build properties the same way the `html!` macro does it. diff --git a/website/docs/concepts/function-components/pure-components.mdx b/website/docs/concepts/function-components/pure-components.mdx index bbd1ac84b..4ae25155b 100644 --- a/website/docs/concepts/function-components/pure-components.mdx +++ b/website/docs/concepts/function-components/pure-components.mdx @@ -2,15 +2,12 @@ title: 'Pure Components' --- -## Pure function definition +A function component is considered [pure] when the returned `Html` is deterministically derived +from its props, and its view function mutates no state or has other side-effects. -A function is considered pure when the return values are deterministic given the same parameters, and it has no side-effects. +[pure]: https://en.wikipedia.org/wiki/Pure_function -## Pure components - -In the same sense component is pure when it does not have any state or side_effects and with the given props always returns the same `Html`. - -For example below is a pure component, for a given prop `is_loading` it will always result in same `Html` without any side effects. +For example below is a pure component. For a given prop `is_loading` it will always result in the same `Html` without any side effects. ```rust use yew::{Properties, function_component, Html, html}; @@ -22,7 +19,7 @@ pub struct Props { #[function_component] fn HelloWorld(props: &Props) -> Html { - if props.is_loading.clone() { + if props.is_loading { html! { "Loading" } } else { html! { "Hello world" } @@ -30,7 +27,13 @@ fn HelloWorld(props: &Props) -> Html { } ``` -## Un-pure components +:::note +If you have an internal pure component that makes no use of hooks and other component machinery, you can often write it instead +as a normal function returning `Html` and avoid a bit of overhead for Yew, related to running the component lifecycle. Use +[expression syntax](concepts/html/literals-and-expressions.mdx#expressions) to render them in `html!`. +::: -Though you probably wonder how can a component even be un-pure if its just a function that is called every render and if it does not use any globals. +## Impure components + +You might wonder if a component can be impure if it does not use any globals, since its just a function that is called every render. This is where the next topic comes in - [hooks](./hooks) diff --git a/website/docs/concepts/function-components/state.mdx b/website/docs/concepts/function-components/state.mdx index a4068a612..e6d58c31c 100644 --- a/website/docs/concepts/function-components/state.mdx +++ b/website/docs/concepts/function-components/state.mdx @@ -6,13 +6,13 @@ title: 'State' This table can be used as a guide when deciding what state storing type fits best for your use case: -| Type | Rerender when? | Scope | -| ---------------------------------------------------- | ---------------------------- | ------------------- | -| [use_state](./hooks/use-state) | got set | component instance | -| [use_state_eq](./hooks/use-state#use_state_eq) | got set with diff. value | component instance | -| [use_reducer](./hooks/use-reducer) | got reduced | component instance | -| [use_reducer_eq](./hooks/use-reducer#use_reducer_eq) | got reduced with diff. value | component instance | -| [use_memo](./hooks/use-memo) | dependencies changed | component instance | -| [use_callback](./hooks/use-callback) | dependencies changed | component instance | -| [use_mut_ref](./hooks/use-mut-ref) | - | component instance | -| a static global variable | - | global, used by all | +| Hook | Type | Rerender when? | Scope | +| ---------------------------------------------------- | -------------------------- | ---------------------------- | ------------------- | +| [use_state](./hooks/use-state) | `T` | got set | component instance | +| [use_state_eq](./hooks/use-state#use_state_eq) | `T: PartialEq` | got set with diff. value | component instance | +| [use_reducer](./hooks/use-reducer) | `T: Reducible` | got reduced | component instance | +| [use_reducer_eq](./hooks/use-reducer#use_reducer_eq) | `T: Reducible + PartialEq` | got reduced with diff. value | component instance | +| [use_memo](./hooks/use-memo) | `Deps -> T` | dependencies changed | component instance | +| [use_callback](./hooks/use-callback) | `Deps -> Callback` | dependencies changed | component instance | +| [use_mut_ref](./hooks/use-mut-ref) | `T` | - | component instance | +| a static global variable | `T` | - | global, used by all | diff --git a/website/docs/concepts/html/lists.mdx b/website/docs/concepts/html/lists.mdx index aad6f565b..0b327494b 100644 --- a/website/docs/concepts/html/lists.mdx +++ b/website/docs/concepts/html/lists.mdx @@ -50,18 +50,17 @@ html! { ## Keyed lists -A keyed list is a optimized list that has keys on all tags. -`key` is a special prop provided by Yew which gives an html element a unique identifier which can be used for optimization purposes. +A keyed list is an optimized list that has keys on **all** children. +`key` is a special prop provided by Yew which gives an html element or component a unique identifier +which is used for optimization purposes inside Yew. :::caution - -Key has to be unique and must not depend on the order of the list. - +Key has to be unique only in each list, in constrast to the global uniqueness of html `id`s. It must not depend on the order of the list. ::: It is always recommended to add keys to lists. -Keys can be added by passing a unique value to the special `key` prop: +Keys can be added by passing a unique `String`, `str` or integer to the special `key` prop: ```rust , ignore use yew::prelude::*; @@ -82,7 +81,7 @@ html! { ### Performance increases -We have [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list) example that lets you test the performance improvements, but here is rough example of testing: +We have [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list) example that lets you test the performance improvements, but here is rough rundown: 1. Go to [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list) hosted demo 2. Add 500 elements. @@ -98,7 +97,9 @@ So just at the time of writing this, for 500 components its a x2 increase of spe ### Detailed explanation Usually you just need a key on every list item when you iterate and the order of data can change. -So lets say you iterate through `["bob","sam","rob"]` ended up with html: +It's used to speed up the reconciliation process when re-rendering the list. + +Without keys, lets assume you iterate through `["bob","sam","rob"]`, ending up with the html: ```html
My name is Bob
@@ -106,12 +107,12 @@ So lets say you iterate through `["bob","sam","rob"]` ended up with html:
My name is rob
``` -Then if your list changed to `["bob","rob"]`, -yew would delete from previous html element with id="rob" and update id="sam" to be id="rob" +Then on the next render, if your list changed to `["bob","rob"]`, yew could delete +the element with id="rob" and update id="sam" to be id="rob" -Now if you had added a key to each element, html would stay the same, but in case where it changed to `["bob","rob"]`, yew would just delete the second html element since it knows which one it is. - -Keys also help for weird cases where yew reuses html elements. +If you had added a key to each element, the initial html would be the same, but after +the render with the modified list, `["bob","rob"]`, yew would just delete the second +html element and leave the rest untouched since it can use the keys to associate them. If you ever encounter a bug/"feature" where you switch from one component to another but both have a div as the highest rendered element. Yew reuses the rendered html div in those cases as an optimization. diff --git a/website/docs/getting-started/build-a-sample-app.mdx b/website/docs/getting-started/build-a-sample-app.mdx index 1dbdc0ce5..0b68b4880 100644 --- a/website/docs/getting-started/build-a-sample-app.mdx +++ b/website/docs/getting-started/build-a-sample-app.mdx @@ -2,9 +2,10 @@ title: 'Build a sample app' --- -## Using a starter template +Once you have the environment ready, you can either choose to use a starter template that contains +the boilerplate needed for a basic Yew app or manually set up a small project. -Once you have the environment ready, you can use the starter template to create the boilerplate needed for a basic Yew app. +## Using a starter template Install [`cargo-generate`](https://github.com/cargo-generate/cargo-generate) by following their installation instructions then run the following command: diff --git a/website/docs/getting-started/editor-setup.mdx b/website/docs/getting-started/editor-setup.mdx index 86ece8c0c..7ec0b4ca0 100644 --- a/website/docs/getting-started/editor-setup.mdx +++ b/website/docs/getting-started/editor-setup.mdx @@ -14,19 +14,36 @@ Using a different editor? Feel free to add instructions for your editor of choic 1. Navigate to File | Settings | Editor | Live Templates. 2. Select Rust and click on the + icon to add a new Live Template. 3. Give it a name and description of your preference. -4. Paste the following snippet in Template Text section. +4. Paste the following snippet(s) into the Template Text section. 5. Change the applicability on the lower right, select Rust > Item > Module -```rust ,ignore -use yew::prelude::*; +For function components, use the following template. +- (Optional) Click on Edit Variable and give `tag` a reasonable default value like "div", with double quotes. + +```rust ,ignore +#[derive(PartialEq, Properties)] +pub struct $Name$Props { +} + +#[function_component] +pub fn $Name$(props: &$Name$Props) -> Html { + html! { + <$tag$>$END$ + } +} +``` + +For struct components, you can use the following more complicated template. + +```rust ,ignore struct $NAME$; -enum Msg { +enum $NAME$Msg { } impl Component for $NAME$ { - type Message = Msg; + type Message = $NAME$Msg; type Properties = (); fn create(ctx: &Context) -> Self { @@ -41,28 +58,6 @@ impl Component for $NAME$ { } ``` -For function components, use the template below. Additionally: - -1. Click on Edit Variable -2. In the `func_name` row, set the Expression column to `snakeCase(NAME)` so that `ComponentName` will be automatically - filled as `component_name` - in the function definition. -3. In the `func_name` row, check "skip if defined" so this autogenerated field won't be navigated to. -4. (Optional) give `tag` a reasonable default value like "div", with double quotes. - -```rust ,ignore -#[derive(Properties, PartialEq, Clone)] -pub struct $Name$Props { -} - -#[function_component($Name$)] -pub fn $func_name$(props: &$Name$Props) -> Html { - html! { - <$tag$>$END$ - } -} -``` - ### VS Code 1. Navigate to File > Preferences > User Snippets. @@ -71,18 +66,32 @@ pub fn $func_name$(props: &$Name$Props) -> Html { ```json { - "Create new Yew component": { - "prefix": "YOUR PREFIX OF CHOICE", + "New Yew function component": { + "prefix": "yewfc", "body": [ - "use yew::prelude::*;", + "#[derive(PartialEq, Properties)]", + "pub struct ${1:ComponentName}Props {}", "", - "pub struct ${1};", + "#[function_component]", + "pub fn $1(props: &${1}Props) -> Html {", + " let ${1}Props {} = props;", + " html! {", + " <${2:div}>$0", + " }", + "}" + ], + "description": "Create a minimal Yew function component" + }, + "New Yew struct component": { + "prefix": "yewsc", + "body": [ + "pub struct ${1:ComponentName};", "", - "pub enum Msg {", + "pub enum ${1}Msg {", "}", "", "impl Component for ${1} {", - " type Message = Msg;", + " type Message = ${1}Msg;", " type Properties = ();", "", " fn create(ctx: &Context) -> Self {", @@ -91,7 +100,7 @@ pub fn $func_name$(props: &$Name$Props) -> Html { "", " fn view(&self, ctx: &Context) -> Html {", " html! {", - " ${0}", + " $0", " }", " }", "}" diff --git a/website/docs/getting-started/examples.mdx b/website/docs/getting-started/examples.mdx index 43145d669..fedd9170b 100644 --- a/website/docs/getting-started/examples.mdx +++ b/website/docs/getting-started/examples.mdx @@ -2,10 +2,15 @@ title: 'Examples' --- -The Yew repository is contains many [examples] (in various states of maintenance). +The Yew repository contains many [examples] (in various states of maintenance). We recommend perusing them to get a feel for how to use different features of the framework. We also welcome Pull Requests and issues for when they inevitably get neglected and need some ♥️ For more details including a list of examples, refer to the [README][examples]. +::: note +Most of the examples have a live deployment that can be found at https://examples.yew.rs/. +Click the shield on their individual README page in their respective sub-folder to navigate to the live demo. +::: + [examples]: https://github.com/yewstack/yew/tree/master/examples diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current.json b/website/i18n/ja/docusaurus-plugin-content-docs/current.json index 809aa07a2..8f32da866 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current.json @@ -23,9 +23,9 @@ "message": "HTML", "description": "The label for category HTML in sidebar docs" }, - "sidebar.docs.category.Function Components": { + "sidebar.docs.category.Components": { "message": "Function Components", - "description": "The label for category Function Components in sidebar docs" + "description": "The label for category Components in sidebar docs" }, "sidebar.docs.category.Advanced topics": { "message": "Advanced topics", @@ -63,34 +63,22 @@ "message": "yew-router", "description": "The label for category yew-router in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies": { + "sidebar.docs.category.Using Basic Web Technologies In Yew": { "message": "Intro With Basic Web Technologies", - "description": "The label for category Intro With Basic Web Technologies in sidebar docs" + "description": "The label for category Using Basic Web Technologies In Yew in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies.link.generated-index.title": { + "sidebar.docs.category.Using Basic Web Technologies In Yew.link.generated-index.title": { "message": "Yew Take on Basic Web Technologies", - "description": "The generated-index page title for category Intro With Basic Web Technologies in sidebar docs" + "description": "The generated-index page title for category Using Basic Web Technologies In Yew in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies.link.generated-index.description": { + "sidebar.docs.category.Using Basic Web Technologies In Yew.link.generated-index.description": { "message": "Yew mostly operates on the idea of keeping everything that a reusable piece of UI may need, in one place - rust files. But also seeks to stay close to the original look of the technology. Explore further to fully grasp what we mean by these statements:", - "description": "The generated-index page description for category Intro With Basic Web Technologies in sidebar docs" + "description": "The generated-index page description for category Using Basic Web Technologies In Yew in sidebar docs" }, "sidebar.docs.category.Hooks": { "message": "Hooks", "description": "The label for category Hooks in sidebar docs" }, - "sidebar.docs.category.Javascript with Rust": { - "message": "Javascript with Rust", - "description": "The label for category Javascript with Rust in sidebar docs" - }, - "sidebar.docs.category.Javascript with Rust.link.generated-index.title": { - "message": "wasm-bindgen", - "description": "The generated-index page title for category Javascript with Rust in sidebar docs" - }, - "sidebar.docs.category.Javascript with Rust.link.generated-index.description": { - "message": "Learn about wasm-bindgen", - "description": "The generated-index page description for category Javascript with Rust in sidebar docs" - }, "sidebar.docs.category.Struct Components": { "message": "Struct Components", "description": "The label for category Struct Components in sidebar docs" diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json index f39a63ea7..5f3e467d2 100644 --- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current.json @@ -23,9 +23,9 @@ "message": "HTML", "description": "The label for category HTML in sidebar docs" }, - "sidebar.docs.category.Function Components": { + "sidebar.docs.category.Components": { "message": "Function Components", - "description": "The label for category Function Components in sidebar docs" + "description": "The label for category Components in sidebar docs" }, "sidebar.docs.category.Advanced topics": { "message": "高级主题", @@ -63,34 +63,22 @@ "message": "yew-router", "description": "The label for category yew-router in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies": { + "sidebar.docs.category.Using Basic Web Technologies In Yew": { "message": "Intro With Basic Web Technologies", - "description": "The label for category Intro With Basic Web Technologies in sidebar docs" + "description": "The label for category Using Basic Web Technologies In Yew in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies.link.generated-index.title": { + "sidebar.docs.category.Using Basic Web Technologies In Yew.link.generated-index.title": { "message": "Yew Take on Basic Web Technologies", - "description": "The generated-index page title for category Intro With Basic Web Technologies in sidebar docs" + "description": "The generated-index page title for category Using Basic Web Technologies In Yew in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies.link.generated-index.description": { + "sidebar.docs.category.Using Basic Web Technologies In Yew.link.generated-index.description": { "message": "Yew mostly operates on the idea of keeping everything that a reusable piece of UI may need, in one place - rust files. But also seeks to stay close to the original look of the technology. Explore further to fully grasp what we mean by these statements:", - "description": "The generated-index page description for category Intro With Basic Web Technologies in sidebar docs" + "description": "The generated-index page description for category Using Basic Web Technologies In Yew in sidebar docs" }, "sidebar.docs.category.Hooks": { "message": "Hooks", "description": "The label for category Hooks in sidebar docs" }, - "sidebar.docs.category.Javascript with Rust": { - "message": "Javascript with Rust", - "description": "The label for category Javascript with Rust in sidebar docs" - }, - "sidebar.docs.category.Javascript with Rust.link.generated-index.title": { - "message": "wasm-bindgen", - "description": "The generated-index page title for category Javascript with Rust in sidebar docs" - }, - "sidebar.docs.category.Javascript with Rust.link.generated-index.description": { - "message": "Learn about wasm-bindgen", - "description": "The generated-index page description for category Javascript with Rust in sidebar docs" - }, "sidebar.docs.category.Struct Components": { "message": "Struct Components", "description": "The label for category Struct Components in sidebar docs" diff --git a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current.json index ed59037b2..aea5f2e5c 100644 --- a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current.json @@ -23,9 +23,9 @@ "message": "HTML", "description": "The label for category HTML in sidebar docs" }, - "sidebar.docs.category.Function Components": { + "sidebar.docs.category.Components": { "message": "Function Components", - "description": "The label for category Function Components in sidebar docs" + "description": "The label for category Components in sidebar docs" }, "sidebar.docs.category.Advanced topics": { "message": "進階主題", @@ -63,34 +63,22 @@ "message": "yew-router", "description": "The label for category yew-router in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies": { + "sidebar.docs.category.Using Basic Web Technologies In Yew": { "message": "Intro With Basic Web Technologies", - "description": "The label for category Intro With Basic Web Technologies in sidebar docs" + "description": "The label for category Using Basic Web Technologies In Yew in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies.link.generated-index.title": { + "sidebar.docs.category.Using Basic Web Technologies In Yew.link.generated-index.title": { "message": "Yew Take on Basic Web Technologies", - "description": "The generated-index page title for category Intro With Basic Web Technologies in sidebar docs" + "description": "The generated-index page title for category Using Basic Web Technologies In Yew in sidebar docs" }, - "sidebar.docs.category.Intro With Basic Web Technologies.link.generated-index.description": { + "sidebar.docs.category.Using Basic Web Technologies In Yew.link.generated-index.description": { "message": "Yew mostly operates on the idea of keeping everything that a reusable piece of UI may need, in one place - rust files. But also seeks to stay close to the original look of the technology. Explore further to fully grasp what we mean by these statements:", - "description": "The generated-index page description for category Intro With Basic Web Technologies in sidebar docs" + "description": "The generated-index page description for category Using Basic Web Technologies In Yew in sidebar docs" }, "sidebar.docs.category.Hooks": { "message": "Hooks", "description": "The label for category Hooks in sidebar docs" }, - "sidebar.docs.category.Javascript with Rust": { - "message": "Javascript with Rust", - "description": "The label for category Javascript with Rust in sidebar docs" - }, - "sidebar.docs.category.Javascript with Rust.link.generated-index.title": { - "message": "wasm-bindgen", - "description": "The generated-index page title for category Javascript with Rust in sidebar docs" - }, - "sidebar.docs.category.Javascript with Rust.link.generated-index.description": { - "message": "Learn about wasm-bindgen", - "description": "The generated-index page description for category Javascript with Rust in sidebar docs" - }, "sidebar.docs.category.Struct Components": { "message": "Struct Components", "description": "The label for category Struct Components in sidebar docs" diff --git a/website/sidebars/docs.js b/website/sidebars/docs.js index f59bfdcc0..d6dc6d655 100644 --- a/website/sidebars/docs.js +++ b/website/sidebars/docs.js @@ -30,22 +30,26 @@ module.exports = { items: [ { type: 'category', - label: 'Intro With Basic Web Technologies', + label: 'Using Basic Web Technologies In Yew', link: { type: 'generated-index', - title: 'Yew Take on Basic Web Technologies', + title: "Yew's Take on Basic Web Technologies", description: - 'Yew mostly operates on the idea of keeping everything that a reusable piece of UI may need, in one place - rust files. But also seeks to stay close to the original look of the technology. Explore further to fully grasp what we mean by these statements:', + 'Yew centrally operates on the idea of keeping everything that a reusable piece of UI may need' + + 'in one place - rust files, while also keeping the underlying technology accessible where necessary. ' + + 'Explore further to fully grasp what we mean by these statements:', }, items: [ 'concepts/basic-web-technologies/html', 'concepts/basic-web-technologies/css', 'concepts/basic-web-technologies/js', + 'concepts/basic-web-technologies/wasm-bindgen', + 'concepts/basic-web-technologies/web-sys', ], }, { type: 'category', - label: 'Function Components', + label: 'Components', link: { type: 'doc', id: 'concepts/function-components/introduction', @@ -71,6 +75,7 @@ module.exports = { 'concepts/function-components/hooks/use-memo', 'concepts/function-components/hooks/use-callback', 'concepts/function-components/hooks/use-context', + 'concepts/function-components/hooks/use-force-update', 'concepts/function-components/hooks/custom-hooks', ], }, @@ -95,20 +100,6 @@ module.exports = { 'concepts/html/conditional-rendering', ], }, - { - type: 'category', - label: 'Javascript with Rust', - link: { - type: 'generated-index', - title: 'wasm-bindgen', - description: 'Learn about wasm-bindgen', - slug: '/concepts/wasm-bindgen', - }, - items: [ - 'concepts/wasm-bindgen/introduction', - 'concepts/wasm-bindgen/web-sys', - ], - }, 'concepts/agents', 'concepts/contexts', 'concepts/router',