refactor(examples): split rx_state into multiple examples

This makes each example show one particular thing, which is much better
than before.

Author: arctic-hen7

examples/core/freezing_and_thawing/.gitignore

@@ -0,0 +1 @@
+.perseus/

examples/core/freezing_and_thawing/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "perseus-example-freezing-and-thawing"
+version = "0.3.2"
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
+sycamore = "0.7"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

examples/core/freezing_and_thawing/README.md

@@ -0,0 +1,3 @@
+# Freezing and Thawing Example
+
+This example shows how state freezing and state thawing work with Perseus' reactive state platform.

examples/rx_state/index.html renamed to examples/core/freezing_and_thawing/index.html

@@ -0,0 +1,17 @@
+use perseus::{ErrorPages, Html};
+use sycamore::view;
+
+pub fn get_error_pages<G: Html>() -> ErrorPages<G> {
+    let mut error_pages = ErrorPages::new(|url, status, err, _| {
+        view! {
+            p { (format!("An error with HTTP code {} occurred at '{}': '{}'.", status, url, err)) }
+        }
+    });
+    error_pages.add_page(404, |_, _, _, _| {
+        view! {
+            p { "Page not found." }
+        }
+    });
+
+    error_pages
+}

examples/core/freezing_and_thawing/src/error_pages.rs

@@ -12,6 +12,6 @@ pub struct AppState {
 #[perseus::autoserde(global_build_state)]
 pub async fn get_build_state() -> RenderFnResult<AppState> {
     Ok(AppState {
-        test: "Hello from the global state build process!".to_string(),
+        test: "Hello World!".to_string(),
     })
 }

examples/rx_state/src/global_state.rs renamed to examples/core/freezing_and_thawing/src/global_state.rs

@@ -0,0 +1,13 @@
+mod error_pages;
+mod global_state;
+mod templates;
+
+use perseus::define_app;
+define_app! {
+    templates: [
+        crate::templates::index::get_template::<G>(),
+        crate::templates::about::get_template::<G>()
+    ],
+    error_pages: crate::error_pages::get_error_pages(),
+    global_state_creator: crate::global_state::get_global_state_creator()
+}

examples/core/freezing_and_thawing/src/lib.rs

@@ -0,0 +1,31 @@
+use perseus::state::Freeze;
+use perseus::{Html, Template};
+use sycamore::prelude::*;
+
+use crate::global_state::AppStateRx;
+
+#[perseus::template_rx(AboutPage)]
+pub fn about_page(_: (), global_state: AppStateRx) -> View<G> {
+    let test = global_state.test;
+    // This is not part of our data model, we do NOT want the frozen app synchronized as part of our page's state, it should be separate
+    let frozen_app = Signal::new(String::new());
+    let render_ctx = perseus::get_render_ctx!();
+
+    view! {
+        p { (test.get()) }
+
+        // When the user visits this and then comes back, they'll still be able to see their username (the previous state will be retrieved from the global state automatically)
+        a(href = "") { "Index" }
+        br()
+
+        // We'll let the user freeze from here to demonstrate that the frozen state also navigates back to the last route
+        button(on:click = cloned!(frozen_app, render_ctx => move |_| {
+            frozen_app.set(render_ctx.freeze());
+        })) { "Freeze!" }
+        p { (frozen_app.get()) }
+    }
+}
+
+pub fn get_template<G: Html>() -> Template<G> {
+    Template::new("about").template(about_page)
+}

examples/core/freezing_and_thawing/src/templates/about.rs

@@ -4,28 +4,30 @@ use sycamore::prelude::*;
 
 use crate::global_state::AppStateRx;
 
-// We define a normal `struct` and then use `make_rx` (which derives `Serialize`, `Deserialize`, and `Clone` automatically)
-// This will generate a new `struct` called `IndexPropsRx` (as we asked it to), in which every field is made reactive with a `Signal`
 #[perseus::make_rx(IndexPropsRx)]
 pub struct IndexProps {
-    pub username: String,
+    username: String,
 }
 
-// This special macro (normally we'd use `template(IndexProps)`) converts the state we generate elsewhere to a reactive version
-// We need to tell it the name of the unreactive properties we created to start with (unfortunately the compiler isn't smart enough to figure that out yet)
-// This will also add our reactive properties to the global state store, and, if they're already there, it'll use the existing one
 #[perseus::template_rx(IndexPage)]
-pub fn index_page(IndexPropsRx { username }: IndexPropsRx, global_state: AppStateRx) -> View<G> {
+pub fn index_page(state: IndexPropsRx, global_state: AppStateRx) -> View<G> {
+    let username = state.username;
     let username_2 = username.clone(); // This is necessary until Sycamore's new reactive primitives are released
-    let frozen_app = Signal::new(String::new()); // This is not part of our data model, so it's not part of the state properties (everything else should be though)
+    let test = global_state.test;
+    let test_2 = test.clone();
+
+    // This is not part of our data model, we do NOT want the frozen app synchronized as part of our page's state, it should be separate
+    let frozen_app = Signal::new(String::new());
     let frozen_app_2 = frozen_app.clone();
     let frozen_app_3 = frozen_app.clone();
     let render_ctx = perseus::get_render_ctx!();
 
     view! {
+        // For demonstration, we'll let the user modify the page's state and the global state arbitrarily
         p { (format!("Greetings, {}!", username.get())) }
         input(bind:value = username_2, placeholder = "Username")
-        p { (global_state.test.get()) }
+        p { (test.get()) }
+        input(bind:value = test_2, placeholder = "Global state")
 
         // When the user visits this and then comes back, they'll still be able to see their username (the previous state will be retrieved from the global state automatically)
         a(href = "about") { "About" }

examples/rx_state/src/index.rs renamed to examples/core/freezing_and_thawing/src/templates/index.rs

@@ -0,0 +1,2 @@
+pub mod about;
+pub mod index;

examples/core/freezing_and_thawing/src/templates/mod.rs

@@ -0,0 +1 @@
+.perseus/

examples/core/idb_freezing/.gitignore

@@ -0,0 +1,13 @@
+[package]
+name = "perseus-example-idb-freezing"
+version = "0.3.2"
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+perseus = { path = "../../../packages/perseus", features = [ "hydrate", "idb-freezing" ] }
+sycamore = "0.7"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+wasm-bindgen-futures = "0.4"

examples/core/idb_freezing/Cargo.toml

@@ -0,0 +1,5 @@
+# IndexedDB Freezing Example
+
+This example shows how Perseus can supprot freezing state to IndexedDB and retrieving it from there later, which is the mechanism of state freezing that many apps will use. This is also the basis of Perseus' HSR system.
+
+Notably, this requires the `wasm-bindgen-futures` package and the `idb-freezing` feature enabled on the `perseus` package.

examples/core/idb_freezing/README.md

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    </head>
+    <body>
+        <div id="root"></div>
+    </body>
+</html>

examples/core/idb_freezing/index.html

@@ -0,0 +1,17 @@
+use perseus::{ErrorPages, Html};
+use sycamore::view;
+
+pub fn get_error_pages<G: Html>() -> ErrorPages<G> {
+    let mut error_pages = ErrorPages::new(|url, status, err, _| {
+        view! {
+            p { (format!("An error with HTTP code {} occurred at '{}': '{}'.", status, url, err)) }
+        }
+    });
+    error_pages.add_page(404, |_, _, _, _| {
+        view! {
+            p { "Page not found." }
+        }
+    });
+
+    error_pages
+}

examples/core/idb_freezing/src/error_pages.rs

@@ -0,0 +1,17 @@
+use perseus::{state::GlobalStateCreator, RenderFnResult};
+
+pub fn get_global_state_creator() -> GlobalStateCreator {
+    GlobalStateCreator::new().build_state_fn(get_build_state)
+}
+
+#[perseus::make_rx(AppStateRx)]
+pub struct AppState {
+    pub test: String,
+}
+
+#[perseus::autoserde(global_build_state)]
+pub async fn get_build_state() -> RenderFnResult<AppState> {
+    Ok(AppState {
+        test: "Hello World!".to_string(),
+    })
+}

examples/core/idb_freezing/src/global_state.rs

@@ -0,0 +1,13 @@
+mod error_pages;
+mod global_state;
+mod templates;
+
+use perseus::define_app;
+define_app! {
+    templates: [
+        crate::templates::index::get_template::<G>(),
+        crate::templates::about::get_template::<G>()
+    ],
+    error_pages: crate::error_pages::get_error_pages(),
+    global_state_creator: crate::global_state::get_global_state_creator()
+}

examples/core/idb_freezing/src/lib.rs

@@ -0,0 +1,46 @@
+use perseus::state::{Freeze, IdbFrozenStateStore};
+use perseus::{Html, Template};
+use sycamore::prelude::*;
+
+use crate::global_state::AppStateRx;
+
+#[perseus::template_rx(AboutPage)]
+pub fn about_page(_: (), global_state: AppStateRx) -> View<G> {
+    let test = global_state.test;
+    // This is not part of our data model
+    let freeze_status = Signal::new(String::new());
+    let render_ctx = perseus::get_render_ctx!();
+
+    view! {
+        p { (test.get()) }
+
+        // When the user visits this and then comes back, they'll still be able to see their username (the previous state will be retrieved from the global state automatically)
+        a(href = "") { "Index" }
+        br()
+
+        // We'll let the user freeze from here to demonstrate that the frozen state also navigates back to the last route
+        button(on:click = cloned!(freeze_status, render_ctx => move |_|
+            // The IndexedDB API is asynchronous, so we'll spawn a future
+            wasm_bindgen_futures::spawn_local(cloned!(render_ctx, freeze_status => async move {
+                // We do this here (rather than when we get the render context) so that it's updated whenever we press the button
+                let frozen_state = render_ctx.freeze();
+                let idb_store = match IdbFrozenStateStore::new().await {
+                    Ok(idb_store) => idb_store,
+                    Err(_) => {
+                        freeze_status.set("Error.".to_string());
+                        return;
+                    }
+                };
+                match idb_store.set(&frozen_state).await {
+                    Ok(_) => freeze_status.set("Saved.".to_string()),
+                    Err(_) => freeze_status.set("Error.".to_string())
+                };
+            }))
+        )) { "Freeze to IndexedDB" }
+        p { (freeze_status.get()) }
+    }
+}
+
+pub fn get_template<G: Html>() -> Template<G> {
+    Template::new("about").template(about_page)
+}

examples/core/idb_freezing/src/templates/about.rs

@@ -2,25 +2,35 @@ use perseus::state::{Freeze, IdbFrozenStateStore, PageThawPrefs, ThawPrefs};
 use perseus::{Html, RenderFnResultWithCause, Template};
 use sycamore::prelude::*;
 
-#[perseus::make_rx(TestPropsRx)]
-pub struct TestProps {
-    pub username: String,
+use crate::global_state::AppStateRx;
+
+#[perseus::make_rx(IndexPropsRx)]
+pub struct IndexProps {
+    username: String,
 }
 
-#[perseus::template_rx(IdbPage)]
-pub fn idb_page(TestPropsRx { username }: TestPropsRx) -> View<G> {
+#[perseus::template_rx(IndexPage)]
+pub fn index_page(state: IndexPropsRx, global_state: AppStateRx) -> View<G> {
+    let username = state.username;
     let username_2 = username.clone(); // This is necessary until Sycamore's new reactive primitives are released
-    let render_ctx = perseus::get_render_ctx!(); // We get the render context out here, it's not accessible in the future
-    let freeze_status = Signal::new(String::new()); // This isn't part of the template's data model, it's just here for demonstration
+    let test = global_state.test;
+    let test_2 = test.clone();
+
+    // This is not part of our data model
+    let freeze_status = Signal::new(String::new());
     let thaw_status = Signal::new(String::new());
+    let render_ctx = perseus::get_render_ctx!();
 
     view! {
+        // For demonstration, we'll let the user modify the page's state and the global state arbitrarily
         p { (format!("Greetings, {}!", username.get())) }
         input(bind:value = username_2, placeholder = "Username")
+        p { (test.get()) }
+        input(bind:value = test_2, placeholder = "Global state")
 
         // When the user visits this and then comes back, they'll still be able to see their username (the previous state will be retrieved from the global state automatically)
         a(href = "about") { "About" }
-        a(href = "") { "Index" }
+        br()
 
         button(on:click = cloned!(freeze_status, render_ctx => move |_|
             // The IndexedDB API is asynchronous, so we'll spawn a future
@@ -76,14 +86,17 @@ pub fn idb_page(TestPropsRx { username }: TestPropsRx) -> View<G> {
 }
 
 pub fn get_template<G: Html>() -> Template<G> {
-    Template::new("idb")
+    Template::new("index")
         .build_state_fn(get_build_state)
-        .template(idb_page)
+        .template(index_page)
 }
 
 #[perseus::autoserde(build_state)]
-pub async fn get_build_state(_path: String, _locale: String) -> RenderFnResultWithCause<TestProps> {
-    Ok(TestProps {
+pub async fn get_build_state(
+    _path: String,
+    _locale: String,
+) -> RenderFnResultWithCause<IndexProps> {
+    Ok(IndexProps {
         username: "".to_string(),
     })
 }

examples/rx_state/src/idb.rs renamed to examples/core/idb_freezing/src/templates/index.rs

@@ -0,0 +1,2 @@
+pub mod about;
+pub mod index;

examples/core/idb_freezing/src/templates/mod.rs

@@ -0,0 +1 @@
+.perseus/

examples/core/rx_state/.gitignore

@@ -6,10 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus", features = [ "hydrate", "idb-freezing" ] }
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-ureq = "2"
-reqwasm = "0.4"
-wasm-bindgen-futures = "0.4"

examples/rx_state/Cargo.toml renamed to examples/core/rx_state/Cargo.toml

@@ -0,0 +1,3 @@
+# Reactive State Example
+
+This example shows some of the power of Perseus' reactive state platform by extending the usual basic Perseus app to show how reactive state can persist between pages through the page state store.

examples/core/rx_state/README.md

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    </head>
+    <body>
+        <div id="root"></div>
+    </body>
+</html>

examples/core/rx_state/index.html

@@ -0,0 +1,17 @@
+use perseus::{ErrorPages, Html};
+use sycamore::view;
+
+pub fn get_error_pages<G: Html>() -> ErrorPages<G> {
+    let mut error_pages = ErrorPages::new(|url, status, err, _| {
+        view! {
+            p { (format!("An error with HTTP code {} occurred at '{}': '{}'.", status, url, err)) }
+        }
+    });
+    error_pages.add_page(404, |_, _, _, _| {
+        view! {
+            p { "Page not found." }
+        }
+    });
+
+    error_pages
+}

examples/core/rx_state/src/error_pages.rs

@@ -0,0 +1,11 @@
+mod error_pages;
+mod templates;
+
+use perseus::define_app;
+define_app! {
+    templates: [
+        crate::templates::index::get_template::<G>(),
+        crate::templates::about::get_template::<G>()
+    ],
+    error_pages: crate::error_pages::get_error_pages()
+}