docs: Finish 0.3.0 docs (#1105)

* docs: Finish 0.3.0 docs

* split main_align and cross_align docs

* add missing imports

* fix native_router doc

* fix native_router doc again

* update docs

* fix link

* update accessibility docs

crates/elements/src/attributes/layout_attributes.rs

@@ -329,7 +329,7 @@ def_attribute!(
     /// ```
     content,
 
-    /// ### main_align & cross_align
+    /// ### main_align
     ///
     /// Control how the inner elements are positioned inside the element. You can combine it with the `direction` attribute to create complex flows.
     ///
@@ -348,10 +348,9 @@ def_attribute!(
     /// - `center`: At the center of the axis (same as in `main_align`)
     /// - `end`: At the end of the axis (same as in `main_align`)
     ///
-    /// When using the `vertical` direction, `main_align` will be the Y axis and `cross_align` will be the X axis. But when using the `horizontal` direction, the
-    /// `main_align` will be the X axis and the `cross_align` will be the Y axis.
+    /// When using the `vertical` direction it uses the Y axis and in `horizontal` direction it uses the X axis.
     ///
-    /// Example on how to center the inner elements in both axis:
+    /// Example on how to center the inner elements in the main axis:
     ///
     /// ```rust, no_run
     /// # use freya::prelude::*;
@@ -361,7 +360,6 @@ def_attribute!(
     ///             width: "100%",
     ///             height: "100%",
     ///             main_align: "center",
-    ///             cross_align: "center",
     ///             rect {
     ///                 width: "50%",
     ///                 height: "50%",
@@ -372,6 +370,38 @@ def_attribute!(
     /// }
     /// ```
     main_align,
+
+    /// ### cross_align
+    ///
+    /// Control how the inner elements are positioned inside the element in the axis perpendicular to the direction.
+    ///
+    /// Accepted values:
+    ///
+    /// - `start` (default): At the begining of the axis (same as in `main_align`)
+    /// - `center`: At the center of the axis (same as in `main_align`)
+    /// - `end`: At the end of the axis (same as in `main_align`)
+    ///
+    /// When using the `vertical` direction it uses the X axis and in `horizontal` direction it uses the Y axis.
+    ///
+    /// Example on how to center the inner elements in the cross axis:
+    ///
+    /// ```rust, no_run
+    /// # use freya::prelude::*;
+    /// fn app() -> Element {
+    ///     rsx!(
+    ///         rect {
+    ///             width: "100%",
+    ///             height: "100%",
+    ///             cross_align: "center",
+    ///             rect {
+    ///                 width: "50%",
+    ///                 height: "50%",
+    ///                 background: "red"
+    ///             },
+    ///         }
+    ///     )
+    /// }
+    /// ```
     cross_align,
 
     /// Specify a space between the inner elements. Think it as a margin for every element but defined by its parent.

crates/freya/src/_docs/async_tasks.rs

@@ -9,6 +9,8 @@
 //!
 //! Important to know: Tasks spawned with `spawn` will be cancelled when the component their were created is dropped. If you want to have an async tasks not attached to the component you may use `spawn_forever`.
 //!
+//! You can learn more in [Dioxus Docs](dioxus_core::prelude::spawn).
+//!
 //! ```rust
 //! # use freya::prelude::*;
 //! fn app() -> Element {

crates/freya/src/_docs/components_and_props.rs

@@ -1,9 +1,9 @@
 //! # Components
 //!
-//! Freya apps will usually be composed of different 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](./ui.md) chapter.
+//! > 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:
 //!
@@ -19,11 +19,10 @@
 //!     )
 //! }
 //! ```
+//! 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.
 //!
-//! This is obviously fine, but the moment our app grows in size and complexity we might want to split
-//! things out in order to maintain a certain level of modularity and reusability. We can do this by spliting the UI in different components
-//!
-//! For example, lets create a reusable component:
+//! Lets create a reusable component:
 //!
 //! ```rust
 //! # use freya::prelude::*;
@@ -55,7 +54,7 @@
 //! }
 //! ```
 //!
-//! 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, so we can later use the component prop in a declarative way in the RSX.
+//! 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:
 //!
@@ -77,9 +76,13 @@
 //!
 //! ## Renders
 //!
-//! Components renders are just when a component function runs, which might be because it is subscribed to a signal and that signal got mutated, or because its props changed.
+//! 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
 //!
-//! > Even though the naming 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 a thousand times but it it doesn't generate a new UI Freya will not rerender it.
+//! > **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:
 //!
@@ -89,15 +92,15 @@
 //! fn CoolComp() -> Element {
 //!     let mut count = use_signal(|| 0);
 //!
-//!     // 1 run of this function means 1 render of this component
+//!     // 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 subscried to any change in the `count` siganal
+//!             // By embedding the count in this text the component is subscribed to any change of the `count` siganal
 //!             "Increase {count}"
 //!         }
 //!     )

crates/freya/src/_docs/hooks.rs

@@ -1,6 +1,6 @@
 //! # Hooks
 //!
-//! Hooks are special functions to be used inside of Components that lets you handle different things like the state or lifecycle of your component. They are usually prefixed with `use`, e.g `use_signal`, `use_effect`, `use_memo`, etc.
+//! Hooks are special functions to be used inside of Components that lets you handle different things like the state or lifecycle of your component. They are usually prefixed with `use`, e.g [`use_signal`](dioxus::hooks::use_signal), [`use_effect`](dioxus::hooks::use_signal), [`use_memo`]((dioxus::hooks::use_memo)), etc.
 //!
 //! # Rules of Hooks
 //!

crates/freya/src/_docs/introduction.rs

@@ -1,15 +1,16 @@
 //! # Introduction
 //!
-//! **Freya** is a Rust 🦀 library to make GUI applications that are **cross-platform**, which means they will run the same way in Windows, macOS and Linux.
+//! **Freya** is a Rust 🦀 library to make GUI applications that are [**cross-platform**](https://en.wikipedia.org/wiki/Cross-platform_software), targeting in Windows, macOS and Linux.
 //!
-//! It uses a model where you compose the app by splitting the UI in different components that return pieces of UI or call other components, this is because
-//! Freya runs on 🧬 [Dioxus](https://dioxuslabs.com), a renderer-agnostic UI library inspired by ReactJS.
+//! Freya uses a [declarative](https://en.wikipedia.org/wiki/Declarative_programming) model for the UI, and components to encapculate the UI in reusable pieces of code. This is because
+//! Freya uses the core crates 🧬 [Dioxus](https://dioxuslabs.com), a renderer-agnostic components-based and declarative UI library inspired by ReactJS.
 //!
-//! Even though you might have seen that Dioxus render to HTML, use CSS/JavaScript/WASM/WebView/WGPU. this does not apply to Freya. In fact, Freya only uses some of the core
-//! crates of Dioxus, which means that you will be writing Dioxus components and using some of its APIs but, the elements, attributes, styling, layout, events, and more things
-//! will be provided by Freya.
+//! You might have seen that Dioxus render to HTML, use CSS/JavaScript/WASM/WebView/WGPU. this does not apply to Freya.
 //!
-//! Freya uses 🎨 [Skia](https://skia.org/) as rendering engine because its a very battle tested library and has great support for a lot of features.
+//! Agin, Freya only uses some of the core crates of Dioxus, meaning that you will be writing Dioxus components and using some of its APIs but, the elements, attributes, styling, layout, events,
+//! and the rest of things will be provided by Freya.
+//!
+//! Freya also uses 🎨 [Skia](https://skia.org/) as rendering engine because its a very battle tested library and has great support for a lot of features.
 //!
 //! #### Example
 //!

crates/freya/src/_docs/mod.rs

@@ -1,4 +1,3 @@
-pub mod accessibility;
 pub mod async_tasks;
 pub mod components_and_props;
 pub mod development_setup;

crates/freya/src/_docs/router.rs

@@ -93,5 +93,4 @@
 //! }
 //! ```
 
-pub mod animated_transitions;
 pub mod native_router;

crates/freya/src/_docs/router/native_router.rs

@@ -6,8 +6,11 @@
 //! You simply need to wrap your `Router` content inside the `NativeRouter` component.
 //!
 //! Example (based on the example from [router](crate::_docs::router)):
-//! ```rust, ignore
-//! #[allow(non_snake_case)]
+//! ```rust, no_run
+//! # use freya::prelude::*;
+//! # use dioxus_router::prelude::*;
+//! # use freya_components::Link;
+//! # #[allow(non_snake_case)]
 //! fn AppSidebar() -> Element {
 //!     rsx!(
 //!         NativeRouter {
@@ -29,4 +32,43 @@
 //!         }
 //!     )
 //! }
+//!   #[rustfmt::skip]
+//!   #[derive(Routable, Clone, PartialEq)]
+//! # pub enum Route {
+//! #     #[layout(AppSidebar)]
+//! #         #[route("/")]
+//! #         Home,
+//! #         #[route("/other")]
+//! #         Other,
+//! #     #[end_layout]
+//! #     #[route("/..route")]
+//! #     PageNotFound { }, // Handle 404 routes.
+//! # }
+//! #
+//! # #[component]
+//! # fn Home() -> Element {
+//! #     rsx!(
+//! #         label {
+//! #             "Home Page"
+//! #         }
+//! #     )
+//! # }
+//! #
+//! # #[component]
+//! # fn Other() -> Element {
+//! #     rsx!(
+//! #         label {
+//! #             "Other Page"
+//! #         }
+//! #     )
+//! # }
+//! #
+//! # #[component]
+//! # fn PageNotFound() -> Element {
+//! #     rsx!(
+//! #         label {
+//! #             "404"
+//! #         }
+//! #     )
+//! # }
 //! ```

crates/freya/src/_docs/state_management.rs

@@ -1,8 +1,6 @@
 //! # State Management
 //!
-//! Dioxus and Freya apps, have multiple ways of state management.
-//!
-//! See the different features:
+//! Here are the multiple built-in ways of state management you can use in Freya:
 //!
 //! - [Signals](crate::_docs::state_management::signals)
 //! - [Global Signals](crate::_docs::state_management::global_signals)

crates/freya/src/_docs/state_management/context.rs

@@ -4,7 +4,9 @@
 //!
 //! ## Prop Drilling
 //!
-//! **Prop drilling** is when you want to pass a certain data from one parent component to some nested component, and you start to declare the same prop in each one of the components in between the parent and the target component. This causes a huge unnecessary boilerplate that can be used by using the Context API.
+//! **Prop drilling** is when you want to pass a certain data from one parent component to some nested component, and you start to declare the same prop in each one of the components in between the parent and the target component.
+//!
+//!  This leads to an huge unnecessary boilerplate that could be avoided by using the Context API.
 //!
 //! ```rust
 //! # use freya::prelude::*;

crates/freya/src/_docs/state_management/lifecycle.rs

@@ -1,9 +1,9 @@
 //! # Lifecycle
 //!
-//! Dioxus components can use hooks to manage certain lifecycle situations.
+//! Dioxus offers hooks to manage the different lifecycle situations of components.
 //!
-//! ## Component creation
-//! You can run certain logic when the component is created for the first time by using the `use_hook` hook.
+//! ## Component created
+//! You can run certain logic when the component is created (also known as mounted or instanciated) for the first time by using the `use_hook` hook.
 //!
 //! ```rust
 //! # use freya::prelude::*;

crates/freya/src/_docs/state_management/signals.rs

@@ -1,39 +1,37 @@
 //! # Signals
 //!
-//! Signals are a state management solution built-in into Dioxus. They are simple reactive value containers that simplify the mutation and reading of state, even across components.
+//! Signals are a state management solution built-in into Dioxus. They allow us to store values so that components can read and subscribe to any change done to the stored value. Signals can even be read and mutated from multiple components.
 //!
-//! They are usually created by using the `use_signal` hook.
+//! They are usually created by using the [`use_signal`](dioxus::prelude::use_signal) hook.
 //!
 //! ### Example
 //!
 //! ```rust
 //! # use freya::prelude::*;
 //! fn app() -> Element {
-//!     let mut count = use_signal(|| 0);
 //!     // The closure passed to `use_signal` will be called only
 //!     // the first time this component renders,
 //!     // it will return the initial value for the Signal.
 //!     // This closure is to prevent having to create the initial value
 //!     // every time the component runs again, as it is only needed the first time.
+//!     let mut count = use_signal(|| 0);
 //!
 //!     let onclick = move |_| {
 //!         count += 1; // Shorthand for count.write() += 1;
-//!         // The moment the signal is mutated it will notify
+//!         // The moment the signal is mutated, it will notify
 //!         // all the components that have a read subscription
 //!         // to this signal (in this case, only `app`)
 //!         // that there has been a change.
-//!         // When that happens they will renders again
-//!         // and thus producing the new UI.
+//!         // When that happens these components will render again
+//!         // so that an updated UI is produced and ultimately presented to the user.
 //!     };
 //!
 //!     rsx!(
 //!         label {
 //!             onclick,
 //!             "{count}"
-//!             // Because the signal is being read here,
-//!             // everytime that it gets mutated, this component
-//!             // will rerender as it has a read subscription.
-//!             // "{count}" is the same as using "{count.read()}".
+//!             // By embedding the `count` signal in here, we are effectively
+//!             // creating a read subscription. It is the same as if was doing`"{count.read()}"`.
 //!         }
 //!     )
 //! }