Refactor

docs/tut/crash-course/6-scope.md

@@ -0,0 +1,102 @@
+# Scopes
+
+Vide operates on the concept of scopes. Vide scopes come in two flavors:
+stable and reactive.
+
+The three main rules for scopes are:
+
+- Stable scopes never rerun.
+- Reactive scopes will rerun on source updates.
+- A reactive scope cannot be created within another reactive scope.
+
+Reactive scopes cannot be created on their own - they must be created within
+a stable scope so that it can be tracked and later destroyed when it is
+no longer needed.
+
+This is the purpose of `root()`, which creates an initial stable scope, which
+all other reactive scopes, such as ones created by `effect()`, can stem from.
+
+When this root reactive scope is destroyed, it will destroy any effects created
+within it, ensuring everything is cleaned up properly.
+
+```lua
+local source = vide.source
+local effect = vide.effect
+
+local function setup()
+    local count = source(0)
+
+    effect(function()
+        print(count())
+    end)
+
+    return count
+end
+
+setup() -- will error since effect() was not called within a stable scope
+
+local count = vide.root(setup) -- runs
+count(1) -- prints "1"
+```
+
+The scope created by `root()` can be destroyed by calling the function it passes
+into the given function.
+
+```lua
+local function setup(destroy)
+    local count = source(0)
+
+    effect(function()
+        print(count())
+    end)
+
+    return count, destroy
+end
+
+local count, destroy = root(setup)
+
+count(1) -- prints "1"
+
+destroy()
+
+count(2) -- effect is destroyed; no longer prints
+```
+
+Vide's reactivity can be represented graphically, as a *reactive graph*.
+
+The reactive graph for the above example looks like so:
+
+```mermaid
+%%{init: {
+    "theme": "base",
+    "themeVariables": {
+        "primaryColor": "#1B1B1F",
+        "primaryTextColor": "#fff",
+        "primaryBorderColor": "#1B1B1F",
+        "lineColor": "#79B8FF",
+        "tertiaryColor": "#161618",
+        "tertiaryBorderColor": "#161618"
+    }
+}}%%
+
+graph
+
+subgraph root
+    direction LR
+    count --> effect
+end
+```
+
+When the root reactive scope created by `root()` is destroyed, the `effect`
+scope will also be destroyed since it was created within it.
+
+This is important because you may have an effect that updates the property of a
+UI instance, meaning the effect is referencing and holding that instance in
+memory. The effect being destroyed will remove this reference, allowing the
+instance to be garbage collected.
+
+You don't need to worry about ensuring all your effects are created within a
+root reactive scope, since you should be creating all your UI and corresponding
+effects within a top-level `root()` call that puts all your UI together. So it
+is safe to assume that any effect you create will be created under this top
+level scope. Vide will prevent you from accidently doing otherwise anyways.