upd

Author: MatheusDS4

src/whackds.md

@@ -31,21 +31,14 @@ ds::comp! {
         let x = ds::use_state::<f64>(|| 0.0);
         let button = ds::use_fixture<Option<UiComponent>>(|| None);
 
-        // For the React.js familiar, use_effect!() here acts
-        // different; by default, the dependencies list is "empty".
-        //
-        // Dependencies are not auto tracked, even because
-        // not just "states" have to be tracked, but also
-        // parameters and derived.
+        // Effect
         ds::use_effect!({
             (*button).unwrap().focus();
-            // cleanup (optional)
-            || {}
         });
 
         ds::xn! {
             <w:VGroup s:color="orange">
-                // Style block scoped to that VGroup tag.
+                // Style sheet scoped to that VGroup tag.
                 <w:Style>
                 r###"
                     :host {
@@ -65,7 +58,7 @@ ds::comp! {
 }
 ```
 
-## Style blocks
+## &lt;w:Style&gt; tag
 
 A component tag accepts `<w:Style> `tags only if it defines a `stylesheets: Option<whack::ds::StyleSheets>` field.
 
@@ -93,7 +86,7 @@ The creator may spread existing style sheets:
 
 ```rust
 <w:Style extend={stylesheets}/>
-    // `stylesheets: Option<whack::ds::StyleSheets>
+    // stylesheets: Option<whack::ds::StyleSheets>
 ```
 
 The creator may pass a `HashMap<String, String>` as arguments to a style sheet...
@@ -154,6 +147,8 @@ bind={|val| {
 
 ## Fields
 
+Component fields are the parameters it receives in the `whack::ds::comp!` macro.
+
 ### String
 
 A field
@@ -269,4 +264,52 @@ Specifying a default value for a field prevents the program from panicking for o
 ```rust
 #[default = v]
 x: T,
+```
+
+## Hooks
+
+`use_state(...)`, `use_fixture(...)`, `use_context(...)` and `use_effect!(...)` are examples of built-in hooks.
+
+Hooks must only appear at the top-level of a WhackDS component, and must not be run conditionally.
+
+## Effects
+
+The `use_effect!` hook (effect) is used for either:
+
+- Running code when component mounts and unmounts (the cleanup)
+- Running code when a list of values change (e.g. states, derived values and parameters)
+
+The effect must explicitly state its dependencies (i.e. it should run when a specific value changes), or it has no dependencies by default.
+
+Here are some examples:
+
+```rust
+whack::ds::use_effect!({
+    // runs whenever component mounts
+});
+
+whack::ds::use_effect!({
+    // runs whenever component mounts
+    // (...)
+
+    || {
+        // cleanup.
+        // runs when component unmounts
+    }
+});
+
+whack::ds::use_effect!({
+    // runs whenever the `x` state changes
+}, [x.get()]);
+
+whack::ds::use_effect!({
+    // runs whenever the `variant` parameter changes
+    // (...)
+
+    || {
+        // cleanup.
+        // runs either before re-running this effect,
+        // or when component is unmounted.
+    }
+}, [variant]);
 ```