diff --git a/docs/api/animation.md b/docs/api/animation.md index 16e48d7..6481cc3 100644 --- a/docs/api/animation.md +++ b/docs/api/animation.md @@ -18,8 +18,8 @@ Returns a new source with a value always moving torwards the input source value. - **Details** - The output source value is updated every step based on the input source - value. + An effect is created to update the new source every frame based on the input + source value. The movement is physically simulated according to a [spring](https://en.wikipedia.org/wiki/Simple_harmonic_motion). diff --git a/docs/api/creation.md b/docs/api/creation.md index 46d54c3..539967d 100644 --- a/docs/api/creation.md +++ b/docs/api/creation.md @@ -18,10 +18,10 @@ target instance. The result of the function is applied to a target in the same way properties are using `create()`. - The function is ran in a new reactive scope, just like + The function is ran in a new stable scope, just like [root()](reactivity-core.md#root). - Returns a function that when called will destroy the reactive scope. + Returns a function that when called will destroy the stable scope. - **Example** @@ -170,7 +170,7 @@ A wrapper for `action()` to listen for property changes. Will run the given callback any time the property is changed, as well as when the action is initially run. - The changed connection is disconnected when the reactive scope the action is - ran in is destroyed. + The changed connection is disconnected when the scope the action is ran in + is destroyed. Runs with an action priority of 1. diff --git a/docs/api/reactivity-core.md b/docs/api/reactivity-core.md index 652c80a..8b860d0 100644 --- a/docs/api/reactivity-core.md +++ b/docs/api/reactivity-core.md @@ -42,11 +42,6 @@ Creates a new source with the given value. Calling the returned source with no argument will return its stored value, calling with an argument will set a new value. - Reading from the source from within a reactive scope will cause changes - to that source to be tracked and anything depending on it to update. - - Sources can be created outside of reactive scopes. - - **Example** ```lua @@ -69,10 +64,10 @@ Runs a side-effect in a new reactive scope on source update. - **Details** - Any time a source referenced in the callback is changed, the callback will + Any time a source referenced in the callback is updated, the callback will be reran. - The callback is ran to initially ran on first call to find dependent sources. + The callback is ran once immediately. - **Example** @@ -108,7 +103,7 @@ Derives a new source in a new reactive scope from existing sources. Anytime its value is recalculated it is also cached, subsequent calls will retun this cached value until it recalculates again. - The callback is ran to initially ran on first call to find dependent sources. + The callback is ran once immediately. - **Example** diff --git a/docs/api/reactivity-flow.md b/docs/api/reactivity-flow.md index 47dafa8..6870367 100644 --- a/docs/api/reactivity-flow.md +++ b/docs/api/reactivity-flow.md @@ -18,12 +18,12 @@ Shows one of two components depending on an input source. Returns a source holding an instance of the currently shown component. When the input source changes from a falsey to a truthy value, the - component will be reran under a new reactive scope. If it changes from a - truthy to falsey value, the reactive scope the component was created in will + component will be reran under a new stable scope. If it changes from a + truthy to falsey value, the stable scope the component was created in will be destroyed, and the returned source will output `nil`, or a fallback component if given. - The fallback component is also ran under a new reactive scope, and destroyed + The fallback component is also ran under a new stable scope, and destroyed when the input source switches back to truthy. ## switch() @@ -41,10 +41,10 @@ Shows one of a set of components depending on an input source and a mapping tabl Returns a source holding an instance of the currently shown component. When the input source changes, the new value will be used to lookup a given - mapping table to get a component, which will be ran under a new reactive - scope. If the input source changes, the reactive scope the component was + mapping table to get a component, which will be ran under a new stable + scope. If the input source changes, the stable scope the component was created in will be destroyed, and a new component created under a new - reactive scope. If no component is found for an input value, the switch will + stable scope. If no component is found for an input value, the switch will output `nil`. - **Example** @@ -82,9 +82,9 @@ Maps each index in a table source to an object. When the input source changes, each *index* in the new table is compared with the last input table. - - For any new index, the `transform` function is ran under a new reactive + - For any new index, the `transform` function is ran under a new stable scope to produce a new instance. - - For any removed index, the reactive scope for that index is destroyed. + - For any removed index, the stable scope for that index is destroyed. - Unchanged indexes are untouched. The transform function is called only ever *once* for each index in the @@ -142,9 +142,9 @@ Maps each value in a table source to an object. When the input source changes, each *value* in the new table is compared with the last input table. Similar to `indexes()` but for values instead of indexes. - - For any new value, the `transform` function is ran under a new reactive + - For any new value, the `transform` function is ran under a new stable scope to produce a new instance. - - For any removed value, the reactive scope for that value is destroyed. + - For any removed value, the stable scope for that value is destroyed. - Unchanged values are untouched. The transform function is only ever called *once* for each value in the @@ -203,7 +203,7 @@ Maps each value in a table source to an object. - Toast notifications. `indexes()` should be used in other cases, especially when your source table - has primitive value. It maps an index to a UI element. + has primitive values. It maps an index to a UI element. e.g. - List of character or weapon stats. @@ -213,6 +213,6 @@ Maps each value in a table source to an object. result in less property updates and less re-renders. One case to note is that `values()` works nicely when animating re-ordering of instances, since the value is not destroyed when indexes are changed, and the source index - can easily be put through a spring. + can be used to animate a change in position for the UI element. -------------------------------------------------------------------------------- diff --git a/docs/api/reactivity-utility.md b/docs/api/reactivity-utility.md index ee82067..7f08657 100644 --- a/docs/api/reactivity-utility.md +++ b/docs/api/reactivity-utility.md @@ -2,7 +2,7 @@ ## cleanup() -Runs a callback anytime a reactive scope is reran or destroyed. +Runs a callback anytime a scope is reran or destroyed. - **Type** @@ -31,8 +31,7 @@ Runs a callback anytime a reactive scope is reran or destroyed. ## untrack() -Runs a given function where any sources read will not be tracked by a reactive -scope. +Runs a given function in a new stable scope. - **Type** @@ -42,8 +41,8 @@ scope. - **Details** - Updates made to a source passed to `untrack()` will not cause updates to - anything depending on that source. + Can be used inside a reactive scope to read from sources you do not want + tracked by the reactive scope. - **Example** @@ -76,7 +75,7 @@ read can still be tracked inside a reactive scope. ## batch() Runs a given function where any source updates made within the function do not -trigger effects until after the function runs. +trigger effects until after the function finishes running. - **Type** diff --git a/docs/api/strict-mode.md b/docs/api/strict-mode.md index a7fca48..570108b 100644 --- a/docs/api/strict-mode.md +++ b/docs/api/strict-mode.md @@ -22,12 +22,12 @@ Currently, strict mode will: 6. Checks for duplicate nested properties at same depth. 7. Better error reporting and stack traces + creation traces of property bindings. -By rerunning derived sources and effects twice each time they update,it helps +By rerunning derived sources and effects twice each time they update, it helps ensure that derived source computations are pure, and that any cleanups made in derived sources or effects are done correctly. Accidental yielding within reactive scopes can break Vide's reactive graph, -which strict mode can catch. +which strict mode will catch. As well as additional safety checks, Vide will dedicate extra resources to recording and better emitting stack traces where errors occur, particularly diff --git a/docs/tut/crash-course/12-actions.md b/docs/tut/crash-course/12-actions.md index 06b431d..176c12e 100644 --- a/docs/tut/crash-course/12-actions.md +++ b/docs/tut/crash-course/12-actions.md @@ -24,6 +24,7 @@ action used to listen for property changes: ```lua local action = vide.action +local effect = vide.effect local cleanup = vide.cleanup local function changed(prop: string, callback: (new) -> ()) @@ -44,9 +45,11 @@ local instance = create "TextBox" { changed("Text", output) } -instance.Text = "foo" +effect(function() + print(output()) +end) -print(output()) -- "foo" +instance.Text = "foo" -- "foo" will be printed from the effect ``` The source `output` will be updated with the new property value any time it is diff --git a/docs/tut/crash-course/2-creation.md b/docs/tut/crash-course/2-creation.md index 6dace52..5e76173 100644 --- a/docs/tut/crash-course/2-creation.md +++ b/docs/tut/crash-course/2-creation.md @@ -3,7 +3,7 @@ Instances are created using `create()`. Parentheses `()` can be omitted when calling functions with string or -table literals which is recommended for brevity. +table literals for brevity. ```lua local create = vide.create