Improve docs

docs/.vitepress/config.ts

@@ -39,9 +39,9 @@ export default defineConfig({
                         { text: "Introduction", link: "/tut/crash-course/1-introduction" },
                         { text: "Element Creation", link: "/tut/crash-course/2-creation" },
                         { text: "Components", link: "/tut/crash-course/3-components" },
-                        { text: "State", link: "/tut/crash-course/4-state" },
-                        { text: "Derived State", link: "/tut/crash-course/5-derived-state" },
-                        { text: "Table State", link: "/tut/crash-course/6-table-state" },
+                        { text: "Source", link: "/tut/crash-course/4-source" },
+                        { text: "Derived Source", link: "/tut/crash-course/5-derived-source" },
+                        { text: "Table Source", link: "/tut/crash-course/6-table-source" },
                         { text: "Property Groups", link: "/tut/crash-course/7-property-groups" },
                     ]
                 },

docs/api/animation.md

@@ -18,8 +18,7 @@ Returns a new state with a dynamically animated value of the source.
 
 - **Details**
 
-    The output state value is updated every frame based on the source state
-    value.
+    The output state value is updated every frame based on the source value.
 
     The change is physically simulated according to a
     [spring](https://en.wikipedia.org/wiki/Simple_harmonic_motion).

docs/api/creation.md

@@ -10,7 +10,7 @@ Creates a new UI element, applying any given properties.
 
     ```lua
     function create(class: string): (Properties) -> Instance
-    function create(instance: Instace): (Properties) -> Instance
+    function create(instance: Instance): (Properties) -> Instance
 
     type Properties = Map<string|number, any>
     ```
@@ -71,7 +71,7 @@ Creates a new UI element, applying any given properties.
         Color: Color3
     })
         return create "Frame" {
-            BackgroundColor3 = Color,
+            BackgroundColor3 = props.Color,
             props.Layout,
             props.Children
         }

docs/api/reactivity-core.md

@@ -4,7 +4,7 @@
 
 ## source()
 
-Creates a new source state with the given value.
+Creates a new source with the given value.
 
 - **Type**
 
@@ -14,11 +14,11 @@ Creates a new source state with the given value.
 
 - **Details**
 
-    Calling the returned state with no arguments will return its stored value,
+    Calling the returned source with no arguments will return its stored value,
     calling with arguments will set a new value.
 
-    Reading from the state from within any reactive scope will cause changes
-    to that state to be tracked and anything depending on it to update.
+    Reading from the source from within any reactive scope will cause changes
+    to that source to be tracked and anything depending on it to update.
 
 - **Example**
 
@@ -32,48 +32,49 @@ Creates a new source state with the given value.
 
 ## watch()
 
-Runs a callback on state change.
+Runs a callback on source update.
 
 - **Type**
 
     ```lua
-    function watch(callback: () -> ()): Unwatch
+    function watch(source: () -> ()): Unwatch
 
     type Unwatch = () -> ()
     ```
 
 - **Details**
 
-    The callback is ran immediately to determine what states are referenced.
+    The source callback is ran immediately to determine what states are
+    referenced.
 
-    Any time a state referenced in the callback is changed, the callback will be
-    reran.
+    Any time a source referenced in the callback is changed, the callback will
+    be reran.
 
     Also returns a function that when called, stops the watcher immediately.
 
     ::: warning
-    `callback()` cannot yield.
+    `source()` cannot yield.
     :::
 
 - **Example**
 
     ```lua
-    local state = wrap(1)
+    local state = source(1)
 
     watch(function()
-        print(state.Value)
+        print(state())
     end)
 
     -- prints 1
 
-    state.Value += 1
+    state(state() + 1)
 
     -- prints 2
     ```
 
 ## derive()
 
-Derives a new state from existing states.
+Derives a new source from existing sources.
 
 - **Type**
 
@@ -83,13 +84,13 @@ Derives a new state from existing states.
 
 - **Details**
 
-    The derived state will have its value recalculated when any source state it
-    derives from is updated.
+    The derived source will have its value recalculated when any source source
+    it derives from is updated.
 
     Anytime its value is recalculated it is also cached, subsequent calls will
     retun this cached value until it recalculates again.
 
-    Takes a callback that is immediately run to determine what states are being
+    Takes a callback that is immediately run to determine what sources are being
     referenced.
 
     ::: warning
@@ -99,7 +100,7 @@ Derives a new state from existing states.
 - **Example**
 
     ```lua
-    local count = wrap(0)
+    local count = source(0)
     local text = derive(function() return `count: {count()}` end)
 
     text() -- "count: 0"
@@ -111,7 +112,7 @@ Derives a new state from existing states.
 
 ## indexes()
 
-Maps each index in a table to an object.
+Maps each index in a table source to an object.
 
 - **Type**
 
@@ -124,17 +125,18 @@ Maps each index in a table to an object.
 - **Details**
 
     The transform function is called only ever *once* for each index in the
-    source table. The first argument is a state containing the index's value and
-    the second argument is just the index.
+    source table. The first argument is a source containing the index's value
+    and the second argument is just the index.
 
-    Anytime a new index is added, the transform function will be called again for
-    that new index.
+    Anytime a new index is added, the transform function will be called again
+    for that new index.
 
     Anytime an existing index value changes, the transform function is not rerun,
-    instead the passed state for that index will update, causing anything
+    instead the source value for that index will update, causing anything
     depending on it to update too.
 
-    Returns a state containing an array of all objects returned by the transform.
+    Returns a state containing an array of all objects returned by the
+    transform.
 
     ::: warning
     `transform()` cannot yield.
@@ -170,7 +172,7 @@ Maps each index in a table to an object.
 
 ## values()
 
-Maps each value in a table to an object.
+Maps each value in a table source to an object.
 
 - **Type**
 
@@ -184,21 +186,28 @@ Maps each value in a table to an object.
 
     The transform function is called only ever *once* for each value in the
     source table. The first argument is the index's value and
-    the second argument is a state containing the index.
+    the second argument is a source containing the index.
 
     Anytime a new value is added, the transform function will be called again
     for that new value.
 
     Anytime an existing value's index changes, the transform function is not
-    rerun, instead the passed state for that value will update, causing anything
+    rerun, instead the source index for that value will update, causing anything
     depending on it to update too.
 
-    Returns a state containing an array of all objects returned by the transform.
+    Returns a state containing an array of all objects returned by the
+    transform.
 
     ::: warning
     `transform()` cannot yield.
     :::
 
+    ::: warning
+    Having primitive values in the source table can cause unexpected behavior,
+    as duplicate primitives can result in multiple index sources being bound
+    to the same UI element.
+    :::
+
 - **Example**
 
     The intended purpose of this function is to map each value in a table to

docs/api/reactivity-utility.md

@@ -16,10 +16,24 @@ Runs a callback anytime a reactive scope is re-ran.
     local data = source(1)
 
     watch(function()
-        local label = create "TextLabel" { Text = data }
+        local label = create "TextLabel" { Text = data() }
 
         cleanup(function()
             label:Destroy()
         end)
     end)
     ```
+
+    ```lua
+    local data = source(1)
+
+    derive(function()
+        local label = create "TextLabel" { Text = data() }
+
+        cleanup(function()
+            label:Destroy()
+        end)
+
+        return label
+    end)
+    ```

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

@@ -7,17 +7,20 @@ 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",
     Position = UDim2.fromScale(0.5, 0.5)
 }
 ```
 
-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,32 +2,30 @@
 
 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),
         Size = UDim2.fromOffset(400, 250),
 
         Position = props.Position,
         Text = props.Text,
-        Callback = props.Callback
+        Activated = props.Activated
     }
 end
 
 local button = Button {
     Position = UDim2.new(),
     Text = "Click me!",
 
-    Callback = function()
+    Activated = function()
         print "clicked"
     end
 }