Improve docs

docs/tut/crash-course/2-creation.md

@@ -7,9 +7,12 @@ local vide = require(path_to_vide)
 local create = vide.create
 ```
 
-`create()` returns a constructor for a given class which then takes a table of
+`create()` returns a constructor for a class which then takes a table of
 properties to assign when creating a new instance for that class.
 
+Luau allows us to omit parentheses `()` when calling functions with string or
+table literals for brevity.
+
 ```lua
 local frame = create "Frame" {
     Name = "Background",
@@ -17,7 +20,7 @@ local frame = create "Frame" {
 }
 ```
 
-String keys are assigned as properties and integer keys are assigned as child
+String keys are treated as properties and integer keys are treated as child
 instances.
 
 ```lua
@@ -40,7 +43,7 @@ create "ScreenGui" {
 }
 ```
 
-To connect to an event, just set the event property name to a function.
+To connect to an event, just assign the event property a function.
 
 All event arguments are passed into the function.
 
@@ -51,10 +54,3 @@ create "TextButton" {
     end
 }
 ```
-
-In short:
-
-- String keys = properties
-  - Function values = events
-  - Non-function values = property values
-- Numeric keys = children

docs/tut/crash-course/3-components.md

@@ -2,16 +2,14 @@
 
 Components are custom-made reusable pieces of UI made from other pieces of UI.
 
-Using components you make your application more modular and better organized.
-
-Components leverage functions to create self-contained UI that can even have
-its own state and behavior.
+By using components you can make your application more modular and better
+organized.
 
 ```lua
 local function Button(props: {
     Position: UDim2,
     Text: string,
-    Callback: () -> ()
+    Activated: () -> ()
 })
     return create "TextButton" {
         BackgroundColor3 = Color3.fromRGB(50, 50, 50),
@@ -19,7 +17,7 @@ local function Button(props: {
 
         Position = props.Position,
         Text = props.Text,
-        Callback = props.Callback
+        Activated = props.Activated
     }
 end
 
@@ -27,7 +25,7 @@ local button = Button {
     Position = UDim2.new(),
     Text = "Click me!",
 
-    Callback = function()
+    Activated = function()
         print "clicked"
     end
 }

docs/tut/crash-course/4-source.md

@@ -1,29 +1,28 @@
-# State
+# Source
 
-State in Vide are the core of reactivity in Vide.
+*Sources* in Vide are special objects that store a single value. They are the
+core of reactivity in Vide, as updates to a source can automatically update
+properties or other sources depending on that source.
 
-State contain values that can change, and when they do change, automatically
-update anything that is using it.
-
-A state object in Vide can be created using
+A source in Vide can be created using
 [`source()`](../../api/reactivity-core.md#source).
 
 ```lua
 local source = vide.source
-```
 
-```lua
 local count = source(0)
 ```
 
-The value of a state can be set by calling it with an argument, and can be read
+The value passed to `source()` is the initial value of the source.
+
+The value of a source can be set by calling it with an argument, and can be read
 by calling it with no arguments.
 
 ```lua
-count(count() + 1) -- increment count state by 1
+count(count() + 1) -- increment source by 1
 ```
 
-Below is an example of a counter component that has state.
+Below is an example of a stateful counter component.
 
 ```lua
 local function Counter()
@@ -39,12 +38,9 @@ local function Counter()
 end
 ```
 
-Any time the source value is set, anything depending on it will automatically be
-updated using the new value.
-
 Vide detects when you assign a function to a property. This is known
 as *binding* and doing so will cause the property to *automatically* update
-whenever a state in that function is updated, by rerunning the function and
+whenever a source in that function is updated, by rerunning the function and
 assigning its return value. You can only bind non-event
 properties, otherwise the function is connected as the event callback.
 
@@ -53,4 +49,23 @@ UI instances, you can just focus on defining how the data maps to UI and
 everything will update when changes occur.
 
 Each call of `Counter {}` will create a new counter element, each with their own
-independent count state.
+independent count.
+
+Since sources are just functions, you can pass an external source to a component
+like so:
+
+```lua
+local function Text(p: {
+    Text: () -> string
+})
+    return create "TextLabel" {
+        Text = p.Text
+    }
+end
+
+local text = source "hi"
+
+Text {
+    Text = text
+}
+```

docs/tut/crash-course/5-derived-source.md

@@ -1,10 +1,10 @@
-# Derived State
+# Derived Source
 
-You can create new state from existing states. This is known as *deriving
-state*.
+You can create new sources from existing sources. This is known as *deriving
+sources*.
 
-A function that wraps a state effectively becomes a state. If a state used
-inside a function is updated, the whole function can be re-ran to recompute
+A function that wraps a source effectively becomes a new source. If a source
+used inside a function is updated, the whole function can be re-ran to recompute
 its value.
 
 ```lua
@@ -22,11 +22,11 @@ create "TextLabel" {
 Sometimes when using expensive computations to derive state, you only want to
 recalculate it once when a source state has changed
 
-If you wrap a source state with a regular function, its value will be recomputed
+If you wrap a source with a regular function, its value will be recomputed
 every time you call that function.
 [`derive()`](../../api/reactivity-core.md#derive) accepts a functions whose
-return value will be cached, so that subsequent calls of this derived state
-will return the same cached value until one of its source states have changed.
+return value will be cached, so that subsequent calls of this derived source
+will return the same cached value until one of its input sources have changed.
 
 ```lua
 local derive = vide.derive
@@ -44,7 +44,8 @@ local factorial = derive(function()
 end)
 ```
 
-This can improve performance for expensive calculations.
+This can improve performance in cases where a source is read from multiple times
+between recalculations, like in the example below:
 
 ```lua
 create "TextLabel" {

docs/tut/crash-course/6-table-source.md

@@ -0,0 +1,66 @@
+# Table Source
+
+Vide has specific functions for dealing with sources that store a table value.
+
+Often, you will have a table of values that will be displayed in a similar
+manner. Rather than manually looping over each value to generate a corresponding
+UI element, Vide provides functions `indexes()` and `values()` to do this for
+you.
+
+`indexes()` maps each *index* in a table to a UI element.
+
+```lua
+local names = source { "a", "b", "c" }
+
+local elements = indexes(names, function(name, i)
+    return create "TextLabel" {
+        Text = function()
+            return "Name: " .. name()
+        end,
+
+        LayoutOrder = i
+    }
+end)
+```
+
+What happens here is the given callback is only ever ran *once* for each index
+in the table. The callback receives two arguments, a *source* containing the
+index's value and then the index itself.
+
+Anytime the value at a corresponding index changes, the source for that index
+value is updated, causing the UI element depending on it to update too.
+
+`values()` behaves similarly, except it maps each *value* in a table to a UI
+element.
+
+```lua
+type Item = {
+    Name: string,
+    Icon: number    
+}
+
+local items = source({} :: Array<Item>)
+
+local elements = indexes(items, function(item, i)
+    return create "ImageLabel" {
+        Image = "rbxassetid://" .. item.Icon,
+        LayoutOrder = i
+    }
+end)
+```
+
+The callback is again only ever ran *once* for each value in the table. The
+callback receives two arguments, a value in the table and then a *source*
+containing the value's corresponding index.
+
+Any time a value in a table changes index, the source for that value is updated,
+causing the UI element position to change.
+
+In certain cases `values()` can cause less recalculation and rerenders than
+`indexes()` like when items are re-arranged and shifted within a table.
+
+It is important that each value in a table is unique when using `values()`,
+and for this reason always using `indexes()` if a table contains primitive
+values.
+
+Both `indexes()` and `values()` return an array of all mapped UI elements.

docs/tut/crash-course/6-table-state.md

@@ -1,35 +0,0 @@
-# Table State
-
-Vide has functions for dealing with table states.
-
-Below is an example using the above `List` class.
-
-```lua
-type Item = {
-    Name: string,
-    Icon: number    
-}
-
-local items = source({} :: Array<Item>)
-
-List {
-    Children = indexes(items, function(item, i)
-        return create "ImageLabel" {
-            Image = function()
-                return "rbxassetid://" .. item().Icon
-            end,
-
-            LayoutOrder = i
-        }
-    end)
-}
-```
-
-Here we map each element in `items` to a value returned by a callback.
-
-The callback is called only *once* per key. The first argument given to the
-callback is a state that has the value of the table key's value.
-
-Anytime the value of the corresponding table key changes, the state value
-changes too. This saves us from having to recreate a UI element any time a
-table index changes.

docs/tut/crash-course/7-property-groups.md

@@ -3,6 +3,8 @@
 Often when creating components from existing components, you can find yourself
 repetitively passing through properties such as size or position.
 
+Example below:
+
 ```lua
 function Background(props: {
     Color: Color3,
@@ -33,7 +35,7 @@ function Menu(props: {
 end
 ```
 
-One way this can be avoided is by using *property nesting*. In Vide, passign a
+One way this can be avoided is by using *property nesting*. In Vide, passing a
 table value inside `props` has special semantics. Any key with a table value is
 not assigned like a property, instead the table is iterated and processed just
 like the outer table is. Any properties in the nested table will be assigned
@@ -70,7 +72,8 @@ Here we created a nested group with the key `Layout` that can accept
 layout-related properties. Any name could be chosen for the key.
 This allows us to write much more concise syntax that is also typecheckable.
 
-The same can be done for properties such as children to pass table of instances.
+In another example we use a key named `Children` to pass arrays of instances to
+be parented.
 
 ```lua
 type Children = {