1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

//! # Components
//!
//! Freya apps are composed of different components.
//! Components are defined in the form functions that might receive some input as **Props** and return the UI as **Element**.
//!
//! > You can learn more about how the UI is defined in the [UI](crate::_docs::ui) chapter.
//!
//! This is how a simple root component looks like:
//!
//! ```rust
//! # use freya::prelude::*;
//! // Usually, the root component of a Freya app is named `app`,
//! // but it is not a requirement
//! fn app() -> Element {
//!     rsx!(
//!         label {
//!             "Hello, World!"
//!         }
//!     )
//! }
//! ```
//! This is perfectly fine but we might consider splitting the app in multiple components as it grows. This would allow to have reusable components
//! and also help maintaining and scaling the app.
//!
//! Lets create a reusable component:
//!
//! ```rust
//! # use freya::prelude::*;
//! fn app() -> Element {
//!     rsx!(
//!         // By declaring this element using `TextLabel`
//!         // we are creating an instance of that component
//!         TextLabel {
//!             text: "Number 1"
//!         }
//!         label {
//!             "Number 2"
//!         }
//!         // Another instance of the same component
//!         TextLabel {
//!             text: "Number 3"
//!         }
//!     )
//! }
//!
//! // Reusable component that we might call as many times we want
//! #[component]
//! fn TextLabel(text: String) -> Element {
//!     rsx!(
//!         label {
//!             "{text}"
//!         }
//!     )
//! }
//! ```
//!
//! Notice how we anotate our `TextLabel` component with the macro `#[component]`, this will transform every argument of the function (just `text: String` in this case) to a component prop.
//!
//! For more complex components you might want to put the props in an external struct intead of using the `#[components]` macro:
//!
//! ```rust
//! # use freya::prelude::*;
//! #[derive(Props, PartialEq, Clone)]
//! struct TextLabelProps {
//!     text: String
//! }
//!
//! fn TextLabel(TextLabelProps { text }: TextLabelProps) -> Element {
//!     rsx!(
//!         label {
//!             "{text}"
//!         }
//!     )
//! }
//! ```
//!
//! ## Renders
//!
//! Components renders are just when a component function runs, this can happen in multiple scanarios:
//!
//! 1. The component just got instanciated for the first time
//! 2. A signal that this component is reading, got changed
//! 3. The component props changed
//!
//! > **Note:** The naming of `render` might give you the impression that it means the app will effectively rerender again, it has nothing to do with it, in fact, a component might render (run its function) a thousand times but generate the exact same RSX, if that was the case Freya would not render it again.
//!
//! Consider this simple component:
//!
//! ```rust
//! # use freya::prelude::*;
//! #[component]
//! fn CoolComp() -> Element {
//!     let mut count = use_signal(|| 0);
//!
//!     // One run of this function means one render of this component
//!     // So, everytime the `count` signal is mutated, the component rerenders/is recalled.
//!
//!     rsx!(
//!         label {
//!             // Update the signal value
//!             onclick: move |_| count += 1,
//!
//!             // By embedding the count in this text the component is subscribed to any change of the `count` siganal
//!             "Increase {count}"
//!         }
//!     )
//! }
//! ```