Feat: dioxus frontend crate

packages/core/src/lib.rs

@@ -1,6 +1,47 @@
-//! Dioxus: a concurrent, functional, virtual dom for any renderer in Rust
+//! <div align="center">
+//!   <h1>🌗🚀 📦 Dioxus</h1>
+//!   <p>
+//!     <strong>A concurrent, functional, virtual DOM for Rust</strong>
+//!   </p>
+//! </div>
+//! Dioxus: a concurrent, functional, reactive virtual dom for any renderer in Rust.
 //!
 //!
+//! Dioxus is an efficient virtual dom implementation for building interactive user interfaces in Rust.
+//! This crate aims to maintain a uniform hook-based, renderer-agnostic UI framework for cross-platform development.
+//!
+//! ## Components
+//! The base unit of Dioxus is the `component`. Components can be easily created from just a function - no traits required:
+//! ```
+//! use dioxus_core::prelude::*;
+//!
+//! fn Example(ctx: Context<()>) -> VNode {
+//!     html! { <div> "Hello world!" </div> }
+//! }
+//! ```
+//! Components need to take a "Context" parameter which is generic over some properties. This defines how the component can be used
+//! and what properties can be used to specify it in the VNode output. All components in Dioxus are hook-based, which might be more
+//! complex than other approaches that use traits + lifecycle events. Alternatively, we provide a "lifecycle hook" if you want more
+//! granualar control with behavior similar to other UI frameworks.
+//!
+//! ## Hooks
+//! Dioxus uses hooks for state management. Hooks are a form of state persisted between calls of the function component. Instead of
+//! using a single struct to store data, hooks use the "use_hook" building block which allows the persistence of data between
+//! function component renders.
+//!
+//! This allows functions to reuse stateful logic between components, simplify large complex components, and adopt more clear context
+//! subscription patterns to make components easier to read.
+//!
+//! ## Supported Renderers
+//! Instead of being tightly coupled to a platform, browser, or toolkit, Dioxus implements a VirtualDOM object which
+//! can be consumed to draw the UI. The Dioxus VDOM is reactive and easily consumable by 3rd-party renderers via
+//! the `Patch` object. See [Implementing a Renderer](docs/8-custom-renderer.md) and the `StringRenderer` classes for information
+//! on how to implement your own custom renderer. We provide 1st-class support for these renderers:
+//! - dioxus-desktop (via WebView)
+//! - dioxus-web (via WebSys)
+//! - dioxus-ssr (via StringRenderer)
+//! - dioxus-liveview (SSR + StringRenderer)
+//!
 
 /// Re-export common types for ease of development use.
 /// Essential when working with the html! macro
@@ -9,12 +50,12 @@
 ///
 pub mod prelude {
     use crate::nodes;
-    pub use crate::virtual_dom::Context;
-    pub use crate::virtual_dom::VirtualDom;
+    pub use crate::virtual_dom::{Context, VirtualDom, FC};
     pub use nodes::iterables::IterableNodes;
     pub use nodes::*;
 
-    // hack "VNode"
+    // TODO @Jon, fix this
+    // hack the VNode type until VirtualNode is fixed in the macro crate
     pub type VirtualNode = VNode;
 
     // Re-export from the macro crate
@@ -24,7 +65,6 @@ pub mod prelude {
 /// The Dioxus Virtual Dom integrates an event system and virtual nodes to create reactive user interfaces.
 ///
 /// This module includes all life-cycle related mechanics, including the virtual dom, scopes, properties, and lifecycles.
-///
 pub mod virtual_dom {
     use super::*;
     use crate::nodes::VNode;
@@ -33,7 +73,12 @@ pub mod virtual_dom {
     /// An integrated virtual node system that progresses events and diffs UI trees.
     /// Differences are converted into patches which a renderer can use to draw the UI.
     pub struct VirtualDom {
-        arena: Arena<Scope>,
+        /// All mounted components are arena allocated to make additions, removals, and references easy to work with
+        /// A generational arean is used to re-use slots of deleted scopes without having to resize the underlying arena.
+        components: Arena<Scope>,
+
+        /// Components generate lifecycle events
+        event_queue: Vec<LifecycleEvent>,
     }
 
     impl VirtualDom {
@@ -51,25 +96,41 @@ pub mod virtual_dom {
         /// This is useful when a component tree can be driven by external state (IE SSR) but it would be too expensive
         /// to toss out the entire tree.
         pub fn new_with_props<T>(root: FC<T>) -> Self {
+            // Set a first lifecycle event to add the component
+            let first_event = LifecycleEvent::Add;
+
             Self {
-                arena: Arena::new(),
+                components: Arena::new(),
+                event_queue: vec![first_event],
             }
         }
     }
 
+    enum LifecycleEvent {
+        Add,
+    }
+
     /// Functional Components leverage the type FC to
     pub type FC<T> = fn(&mut Context<T>) -> VNode;
 
     /// The Scope that wraps a functional component
     /// Scope's hold subscription, context, and hook information, however, it is allocated on the heap.
-    pub struct Scope {}
+    pub struct Scope {
+        hook_idx: i32,
+        hooks: Vec<()>,
+    }
 
     impl Scope {
         fn new<T>() -> Self {
-            Self {}
+            Self {
+                hook_idx: 0,
+                hooks: vec![],
+            }
         }
     }
 
+    pub struct HookState {}
+
     /// Components in Dioxus use the "Context" object to interact with their lifecycle.
     /// This lets components schedule updates, integrate hooks, and expose their context via the context api.
     ///
@@ -92,7 +153,12 @@ pub mod virtual_dom {
     }
 
     pub trait Properties {}
+
+    // Auto derive for pure components
     impl Properties for () {}
+
+    // Set up a derive macro
+    // #[derive(Macro)]
 }
 
 /// Virtual Node Support
@@ -600,9 +666,8 @@ pub mod nodes {
     }
 }
 
-///
-///
-///
+/// The diffing algorithm to compare two VNode trees and generate a list of patches to update the VDom.
+/// Currently, using an index-based patching algorithm
 ///
 pub mod diff {
     use super::*;