small fixes for guide and add CSS chapter

Author: wishawa

examples/guide-project/src/extras/css.rs

@@ -0,0 +1,56 @@
+use async_ui_web::{html::Div, NoChild};
+
+// ANCHOR: no-shortcut
+async fn div_with_class() {
+    let div = Div::new();
+    div.class_list().add_1("my-container").expect("?!?!");
+    div.render(NoChild).await;
+}
+// ANCHOR_END: no-shortcut
+
+// ANCHOR: shortcut-imperative
+use async_ui_web::shortcut_traits::ShortcutClassList; // 👈 new import!
+async fn div_with_class_2() {
+    let div = Div::new();
+
+    // 👇 `add_class` provided by the trait
+    div.add_class("my-container");
+    // 👇 `add_classes` for multiple classes
+    div.add_classes(["my-class", "another-class"]);
+
+    div.render(NoChild).await;
+}
+// ANCHOR_END: shortcut-imperative
+// ANCHOR: shortcut-builder
+use async_ui_web::shortcut_traits::ShortcutClassListBuilder; // 👈 new import!
+async fn div_with_class_3() {
+    Div::new()
+        // 👇 add classes without putting `Div` in a variable
+        .with_classes(["my-class", "another-class"])
+        .render(NoChild)
+        .await;
+}
+// ANCHOR_END: shortcut-builder
+// ANCHOR: embedded-css
+mod style {
+    // 👇 Write our CSS here!
+    async_ui_web::css!(
+        "
+.my-class {
+	border: 2px solid red;
+}
+/* Supports any selector */
+.flex.my-class:not(:hover) {
+	background-color: green;
+}
+		"
+    );
+}
+async fn div_with_style() {
+    Div::new()
+        // 👇 the `style::my_class` constant is generated by the macro
+        .with_class(style::my_class)
+        .render(NoChild)
+        .await;
+}
+// ANCHOR_END: embedded-css

examples/guide-project/src/extras/mod.rs

@@ -0,0 +1 @@
+mod css;

examples/guide-project/src/lib.rs

@@ -10,3 +10,4 @@ async fn app() {
 mod building_ui;
 mod dynamicity;
 mod events;
+mod extras;

guide/src/SUMMARY.md

@@ -11,7 +11,7 @@
 - [Building the UI](./building-ui/README.md)
 	- [Your First Component](./building-ui/1-first-component.md)
 	- [Building Nested HTML](./building-ui/2-nested-html.md)
-	- [All the HTML](./building-ui/3-html-components.md)
+	- [All the HTML](./building-ui/3-all-the-html.md)
 	- [Making Siblings](./building-ui/4-siblings.md)
 	- [Components](./building-ui/5-components.md)
 
@@ -22,6 +22,8 @@
 
 - [Handling Events](./events/README.md)
 - [Reactivity and State Management](./reactive/README.md)
-
+- [Extras](./extras/README.md)
+	- [CSS Styling](./extras/css.md)
 # Framework Design & Internals
-- [Framework Design](./in-depth/framework-design.md)
+- [Framework Design](./in-depth/framework-design.md)
+- [Future Work: Other Backends](./in-depth/other-backends.md)

guide/src/building-ui/3-html-components.md renamed to guide/src/building-ui/3-all-the-html.md

@@ -1,4 +1,4 @@
-# Making Siblings with Join
+# Making Siblings
 
 We've so far seen how to render HTML elements and nest them.
 

guide/src/building-ui/4-siblings.md

@@ -1,6 +1,6 @@
 # The DynamicSlot Component
 
-The last subchapter covered dynaimcally *updating* HTML elements.
+The previous subchapter covered dynamically *updating* HTML elements.
 Now we'll be *adding* and *removing* elements.
 
 The [`DynamicSlot` component](https://docs.rs/async_ui_web/latest/async_ui_web/components/struct.DynamicSlot.html)

guide/src/dynamicity/2-dynamic-slot.md

@@ -0,0 +1,4 @@
+# Extras
+
+The content covered up to here should be sufficient to build any application,
+but there are a few more things that Async UI provides...

guide/src/extras/README.md

@@ -0,0 +1,47 @@
+# CSS Styling
+
+## Class List Shortcuts
+You can already do basic styling by accessing your elements `style` property
+([MDN doc](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style),
+[web-sys doc](https://docs.rs/web-sys/latest/web_sys/struct.HtmlElement.html#method.style)).
+
+You can also already do CSS styling by setting classnames
+for your elements with the `classList`
+([MDN doc](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList),
+[web-sys doc](https://docs.rs/web-sys/latest/web_sys/struct.Element.html#method.class_list))
+```rust
+{{ #include ../../../examples/guide-project/src/extras/css.rs:no-shortcut }}
+```
+
+For extra convenience, Async UI provides a few traits to make styling code a bit
+less verbose.
+
+### `ShortcutClassList`
+```rust
+{{ #include ../../../examples/guide-project/src/extras/css.rs:shortcut-imperative }}
+```
+There are a few more methods available.
+View the documentation [here](https://docs.rs/async_ui_web/latest/async_ui_web/shortcut_traits/trait.ShortcutClassList.html).
+### `ShortcutClassListBuilder`
+```rust
+{{ #include ../../../examples/guide-project/src/extras/css.rs:shortcut-builder }}
+```
+View the documentation [here](https://docs.rs/async_ui_web/latest/async_ui_web/shortcut_traits/trait.ShortcutClassListBuilder.html).
+
+## Linking CSS
+
+You can already add your CSS content by either
+*	linking it in your `index.html` (with a `<link />` tag), or
+*	constructing a `<style>` element with Async UI.
+
+Async UI provide an extra mechanism that let you write your CSS in Rust file.
+```rust
+{{ #include ../../../examples/guide-project/src/extras/css.rs:embedded-css }}
+```
+With this method, you don't have to worry about linking the CSS - 
+it is done automatically by the macro.
+
+The macro will add random **postfix** to your CSS class names so that
+you don't have to worry about name collision.
+
+The macro expose those postfixed class names as Rust `&str` constants you can use.

guide/src/extras/css.md

@@ -1 +1,96 @@
-# Framework Design
+# Framework Design
+
+## Design
+
+### Basics
+*	UI as side effect: Rust [Future](https://doc.rust-lang.org/nightly/core/future/trait.Future.html)
+	objects can render things.
+	*	These Futures are long-running. Their UI elements stay on the screen
+		until they are dropped.
+
+### DOM
+*	HTML structure is built by joining and nesting Futures.
+	*	The "base" Future is [ContainerNodeFuture](https://docs.rs/async_ui_web_core/latest/async_ui_web_core/struct.ContainerNodeFuture.html).
+		It puts a single HTML node on the screen.
+		It use the described context to insert its node on first poll,
+		and remove the node when dropped.
+	*	The code for joining is based on [futures-concurrency](https://docs.rs/futures-concurrency/),
+		but rewritten to significantly improve performance and reduce allocations.
+*	We use an implicit rendering context, provided as a scoped thread-local set
+	for each Future `poll`. The context provides the information needed for
+	[`insertBefore`](https://developer.mozilla.org/en-US/docs/Web/API/Node/insertBefore)
+	*	The HTML element that the polled Future should insert its own element to.
+		This is the "parent element".
+	*	An ordered map containing all the children of the parent element,
+		each keyed by a lexicographical "path" from the parent element.
+		```rust
+		Div::new().render( // this Div is the parent element for A-F
+		join((
+			A, // path = [0]
+			join((
+				C, // path = [1, 0]
+				D, // path = [1, 1]
+				join((
+					E, // path = [1, 2, 0]
+					F, // path = [1, 2, 1]
+				))
+			)),
+			B, // path = [2]
+			Div::new().render( // this Div is the parent of G and H
+			join((
+				G, // path = [0]
+				H, // path = [1]
+			))
+			),
+		))
+		)
+		```
+		```html
+		<div>
+			A
+			C
+			D
+			E
+			F
+			B
+			<div>
+				G
+				H
+			</div>
+		</div>
+		```
+		*	The "path" is stored as a `SmallVec<[u32; 4]>`.
+*	No diffing virtual DOM. Dynamicity is special case
+	([DynamicSlot](https://docs.rs/async_ui_web/latest/async_ui_web/components/struct.DynamicSlot.html)).
+*	The event listener [EventFutureStream](https://docs.rs/async_ui_web/latest/async_ui_web/event_handling/struct.EventFutureStream.html)
+	type add a callback to put the event object in a cell and wake its waker.
+	On every poll it the check if there is an event in the cell.
+
+### State
+*	We don't provide reactivity or state management.
+*	State can be put in Future objects.
+	*	Usually, this comes in the form of variables in async functions.
+
+### Scheduling
+*	The whole app is one big Future.
+*	A "main" async executor is provided ([async-executor](https://docs.rs/async-executor/)).
+	It drives the app Future and can also be used to spawn things.
+*	The main executor is driven by a hand-rolled "root" executor.
+	*	The root executor `setTimeout` itself to execute when woken.
+
+## Comparisons
+*	The UI-as-side-effect design of Async UI is quite unique, as far as I know.
+	*	Blocking UI (like [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert)
+		or [`MessageBox`](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messagebox))
+		technically present UI as side-effect too, but they're not very flexible
+		since they block the entire application.
+*	Async UI has long-living async functions and store component state as
+	variables in functions. This approach is similar to [Crank.js](https://crank.js.org/).
+
+## Motivations
+Async UI is motivated by the fact that async is an effect system, and in many cases,
+UI is too.
+
+But that isn't the only possible motive for this framework design.
+[This blog post by *notgull*](https://notgull.github.io/async-gui/) describes
+the same idea of using async for UI, but from a less abstracted perspective.