- - Animation -
- -Utilities for adding transitions and animations to state objects. - ------ - -
-
-
\ No newline at end of file
diff --git a/docs/api-reference/animation/members/spring.md b/docs/api-reference/animation/members/spring.md
new file mode 100644
index 000000000..f0b61d8b8
--- /dev/null
+++ b/docs/api-reference/animation/members/spring.md
@@ -0,0 +1,92 @@
+
+
+
-### Types
-
-
-
- Animatable
- :octicons-chevron-right-24:
-
-
-
-
-### State Objects
-
-
-
- Spring
- :octicons-chevron-right-24:
-
-
-
-
- Tween
- :octicons-chevron-right-24:
-
-
-
-+ + Spring + + -> Spring<T> + +
+ +```Lua +function Fusion.Spring+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ goalState + + : StateObject<T> + +
+ +The goal state that this object should follow. For best results, `T` should be +[animatable](../../types/animatable). + ++ speed + + : CanBeState<T>? + +
+ +Multiplies how fast the motion should occur; doubling the `speed` exactly halves +the time it takes for the motion to complete. + ++ damping + + : CanBeState<T>? + +
+ +The amount of resistance the motion encounters. 0 represents no resistance, +1 is just enough resistance to prevent overshoot (critical damping), and larger +values damp out inertia effects and straighten the motion. + +----- + ++ Returns + + -> Spring<T> + +
+ +A freshly constructed spring state object. + +----- + +## Learn More + +- [Springs tutorial](../../../../tutorials/animation/springs) \ No newline at end of file diff --git a/docs/api-reference/animation/members/tween.md b/docs/api-reference/animation/members/tween.md new file mode 100644 index 000000000..c169657dc --- /dev/null +++ b/docs/api-reference/animation/members/tween.md @@ -0,0 +1,79 @@ + + ++ + Tween + + -> Tween<T> + +
+ +```Lua +function Fusion.Tween+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ goalState + + : StateObject<T> + +
+ +The goal state that this object should follow. For best results, `T` should be +[animatable](../../types/animatable). + ++ info + + : CanBeState<TweenInfo>? + +
+ +Determines the easing curve that the motion will follow. + +----- + ++ Returns + + -> Tween<T> + +
+ +A freshly constructed tween state object. + +----- + +## Learn More + +- [Tweens tutorial](../../../../tutorials/animation/tweens) \ No newline at end of file diff --git a/docs/api-reference/animation/spring.md b/docs/api-reference/animation/spring.md deleted file mode 100644 index ec4bca534..000000000 --- a/docs/api-reference/animation/spring.md +++ /dev/null @@ -1,125 +0,0 @@ - - -- - Spring - - state object - since v0.1 - -
- -Follows the value of another state object, as if linked by a damped spring. - -If the state object is not [animatable](./animatable.md), the spring will -just snap to the goal value. - -```Lua -( - goal: StateObject- since v0.2 -
- -### :octicons-code-24: Spring:setPosition() - -Instantaneously moves the spring to a new position. This does not affect the -velocity of the spring. - -If the given value doesn't have the same type as the spring's current value, -the position will snap instantly to the new value. - -```Lua -(newPosition: T) -> () -``` - -#### Parameters - -- `newPosition` - The value the spring's position should jump to. - ------ - -- since v0.2 -
- -### :octicons-code-24: Spring:setVelocity() - -Overwrites the velocity of this spring. This does not have an immediate effect -on the position of the spring. - -If the given value doesn't have the same type as the spring's current value, -the velocity will snap instantly to the new value. - -```Lua -(newVelocity: T) -> () -``` - -#### Parameters - -- `newVelocity` - The value the spring's velocity should jump to. - ------ - -- since v0.2 -
- -### :octicons-code-24: Spring:addVelocity() - -Adds to the velocity of this spring. This does not have an immediate effect -on the position of the spring. - -If the given value doesn't have the same type as the spring's current value, -the velocity will snap instantly to the new value. - -```Lua -(deltaVelocity: T) -> () -``` - -#### Parameters - -- `deltaVelocity` - The velocity to add to the spring. - ------ - -## Example Usage - -```Lua -local position = Value(UDim2.fromOffset(25, 50)) -local smoothPosition = Spring(position, 25, 0.6) - -local ui = New "Frame" { - Parent = PlayerGui.ScreenGui, - Position = smoothPosition -} - -while true do - task.wait(5) - -- apply an impulse - smoothPosition:addVelocity(UDim2.fromOffset(-10, 10)) -end -``` \ No newline at end of file diff --git a/docs/api-reference/animation/tween.md b/docs/api-reference/animation/tween.md deleted file mode 100644 index 15a361e33..000000000 --- a/docs/api-reference/animation/tween.md +++ /dev/null @@ -1,52 +0,0 @@ - - -- - Tween - - state object - since v0.1 - -
- -Follows the value of another state object, by tweening towards it. - -If the state object is not [animatable](./animatable.md), the tween will -just snap to the goal value. - -```Lua -( - goal: StateObject+ + Animatable +
+ +```Lua +export type Animatable = + number | + CFrame | + Color3 | + ColorSequenceKeypoint | + DateTime | + NumberRange | + NumberSequenceKeypoint | + PhysicalProperties | + Ray | + Rect | + Region3 | + Region3int16 | + UDim | + UDim2 | + Vector2 | + Vector2int16 | + Vector3 | + Vector3int16 +``` + +Any data type that Fusion can decompose into a tuple of animatable parameters. + +!!! note "Passing other types to animation objects" + Other types can be passed to `Tween` and `Spring` objects, however those + types will not animate. Instead, non-`Animatable` types will immediately + arrive at their goal value. + +----- + +## Learn More + +- [Tweens tutorial](../../../../tutorials/animation/tweens) +- [Springs tutorial](../../../../tutorials/animation/springs) \ No newline at end of file diff --git a/docs/api-reference/animation/types/spring.md b/docs/api-reference/animation/types/spring.md new file mode 100644 index 000000000..98655730a --- /dev/null +++ b/docs/api-reference/animation/types/spring.md @@ -0,0 +1,101 @@ + + ++ + Spring +
+ +```Lua +export type Spring+ kind + + : "Spring" + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of state object apart. + +----- + +## Methods + ++ setPosition + + -> () + +
+ +```Lua +function Spring:setPosition( + newPosition: T +): () +``` + +Immediately snaps the spring to the given position. The position must have the +same `typeof()` as the goal state. + ++ setVelocity + + -> () + +
+ +```Lua +function Spring:setVelocity( + newVelocity: T +): () +``` + +Overwrites the spring's velocity without changing its position. The velocity +must have the same `typeof()` as the goal state. + ++ addVelocity + + -> () + +
+ +```Lua +function Spring:addVelocity( + deltaVelocity: T +): () +``` + +Appends to the spring's velocity without changing its position. The velocity +must have the same `typeof()` as the goal state. + +----- + +## Learn More + +- [Springs tutorial](../../../../tutorials/animation/springs) \ No newline at end of file diff --git a/docs/api-reference/animation/types/tween.md b/docs/api-reference/animation/types/tween.md new file mode 100644 index 000000000..dab6ac00b --- /dev/null +++ b/docs/api-reference/animation/types/tween.md @@ -0,0 +1,44 @@ + + ++ + Tween +
+ +```Lua +export type Tween+ kind + + : "Tween" + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of state object apart. + +----- + +## Learn More + +- [Tweens tutorial](../../../../tutorials/animation/tweens) \ No newline at end of file diff --git a/docs/api-reference/errors/index.md b/docs/api-reference/errors/index.md deleted file mode 100644 index 89c95fad1..000000000 --- a/docs/api-reference/errors/index.md +++ /dev/null @@ -1,1107 +0,0 @@ - - -- - Errors -
- -Whenever Fusion outputs any errors or messages to the console, it will have a -short error ID at the end. This is used to uniquely identify what kind of error -or message you're seeing. - -Use the search box below to paste in or type an error ID, and it will scroll to -the details for you. - - - - - - ------ - -
-
- since v0.3 -
- -## attributeNameNil - -``` -Attribute name cannot be nil. -``` - -This message occurs when you try to set an attribute with a 'nil' name. -This error shouldn't occur, however it is a failsafe incase something goes wrong. - -```Lua -local folder = New "Configuration" { - [Attribute(nil)] = "Foo" -} -``` - ------ - -
-
-
------
-
-- since v0.1 -
- -## cannotAssignProperty - -``` -The class type 'Foo' has no assignable property 'Bar'. -``` - -This message means you tried to set a property on an instance, but the property -can't be assigned to. This could be because the property doesn't exist, or -because it's locked by Roblox to prevent edits. - -This usually occurs with the [New](../instances/new) or -[Hydrate](../instances/hydrate) functions: - -```Lua -local folder = New "Folder" { - DataCost = 12345, - ThisPropertyDoesntExist = "Example" -} -``` - -!!! tip - Different scripts may have different privileges - for example, plugins will - be allowed more privileges than in-game scripts. Make sure you have the - necessary privileges to assign to your properties! -
-
-
------
-
-- since v0.1 -
- -## cannotConnectChange - -``` -The Frame class doesn't have a property called 'Foo'. -``` - -This message means you tried to connect to a property change event, but the -property you specify doesn't exist on the instance. - -This usually occurs with the [New](../instances/new) or -[Hydrate](../instances/hydrate) functions: - -```Lua -local textBox = New "TextBox" { - [OnChange "ThisPropertyDoesntExist"] = function() - ... - end) -} -``` -
-
- since v0.3 -
- -## cannotConnectAttributeChange - -``` -The Configuration class doesn't have an attribute called 'Foo'. -``` - -This message means you tried to connect to an attribute change event, however -the connection failed to register. - -```Lua --- How does an example for this work? --- An attribute change shouldn't fail, as GetAttributeChangedSignal --- doesn't error if the attribute doesn't exist. -``` - ------ - -
-
-
------
-
-- since v0.1 -
- -## cannotConnectEvent - -``` -The Frame class doesn't have an event called 'Foo'. -``` - -This message means you tried to connect to an event on an instance, but the -event you specify doesn't exist on the instance. - -This usually occurs with the [New](../instances/new) or -[Hydrate](../instances/hydrate) functions: - -```Lua -local button = New "TextButton" { - [OnEvent "ThisEventDoesntExist"] = function() - ... - end) -} -``` -
-
-
------
-
-- since v0.1 -
- -## cannotCreateClass - -``` -Can't create a new instance of class 'Foo'. -``` - -This message means you tried to create a new instance type, but the type of -instance you specify doesn't exist in Roblox. - -This usually occurs with the [New](../instances/new) function: - -```Lua -local instance = New "ThisClassTypeIsInvalid" { - ... -} -``` -
-
-
------
-
-- since v0.1 -
- -## computedCallbackError - -``` -Computed callback error: attempt to index a nil value -``` - -This message means the callback of a [computed object](../state/computed) -encountered an error. - -```Lua -local example = Computed(function() - local badMath = 2 + "fish" -end) -``` -
-
-
------
-
-- since v0.2 -
- -## destructorNeededComputed - -``` -To return instances from Computeds, provide a destructor function. This will be an error soon - see discussion #183 on GitHub. -``` - -This message shows if you return destructible values from a -[computed object](../state/computed), without also specifying how to destroy -those values using a destructor. - -[Learn more by visiting this discussion on GitHub.](https://github.com/Elttob/Fusion/discussions/183) - -```Lua -local badComputed = Computed(function() - return New "Folder" { ... } -end, nil) -``` -
-
-
------
-
-- since v0.2 -
- -## destructorNeededForKeys - -``` -To return instances from ForKeys, provide a destructor function. This will be an error soon - see discussion #183 on GitHub. -``` - -This message shows if you return destructible values from a -[ForKeys object](../state/forkeys), without also specifying how to destroy -those values using a destructor. - -[Learn more by visiting this discussion on GitHub.](https://github.com/Elttob/Fusion/discussions/183) - -```Lua -local badForKeys = ForKeys(array, function(key) - return New "Folder" { ... } -end, nil) -``` - -!!! note - For some time during the development of v0.2, `ForKeys` would implicitly - insert a destructor for you. This behaviour still works, but it's going to - be removed in an upcoming version. -
-
-
------
-
-- since v0.2 -
- -## destructorNeededForPairs - -``` -To return instances from ForPairs, provide a destructor function. This will be an error soon - see discussion #183 on GitHub. -``` - -This message shows if you return destructible values from a -[ForPairs object](../state/forpairs), without also specifying how to destroy -those values using a destructor. - -[Learn more by visiting this discussion on GitHub.](https://github.com/Elttob/Fusion/discussions/183) - -```Lua -local badForPairs = ForPairs(array, function(key, value) - return key, New "Folder" { ... } -end, nil) -``` - -!!! note - For some time during the development of v0.2, `ForPairs` would implicitly - insert a destructor for you. This behaviour still works, but it's going to - be removed in an upcoming version. -
-
-
------
-
-- since v0.2 -
- -## destructorNeededForValues - -``` -To return instances from ForValues, provide a destructor function. This will be an error soon - see discussion #183 on GitHub. -``` - -This message shows if you return destructible values from a -[ForValues object](../state/forvalues), without also specifying how to destroy -those values using a destructor. - -[Learn more by visiting this discussion on GitHub.](https://github.com/Elttob/Fusion/discussions/183) - -```Lua -local badForValues = ForValues(array, function(value) - return New "Folder" { ... } -end, nil) -``` - -!!! note - For some time during the development of v0.2, `ForValues` would implicitly - insert a destructor for you. This behaviour still works, but it's going to - be removed in an upcoming version. -
-
-
------
-
-- since v0.2 -
- -## forKeysDestructorError - -``` -ForKeys destructor error: attempt to index a nil value -``` - -This message means the destructor passed to a [ForKeys object](../state/forkeys) -encountered an error. - -```Lua -local function destructor(x) - local badMath = 2 + "fish" -end - -local example = ForKeys(array, doSomething, destructor) -``` -
-
-
------
-
-- since v0.2 -
- -## forKeysKeyCollision - -``` -ForKeys should only write to output key 'Charlie' once when processing key changes, but it wrote to it twice. Previously input key: 'Alice'; New input key: 'Bob' -``` - -This message means you returned the same value twice for two different keys in -a [ForKeys object](../state/forkeys). - -```Lua -local data = { - Alice = true, - Bob = true -} -local example = ForKeys(data, function(key) - if key == "Alice" or key == "Bob" then - return "Charlie" - end -end) -``` -
-
-
------
-
-- since v0.2 -
- -## forKeysProcessorError - -``` -ForKeys callback error: attempt to index a nil value -``` - -This message means the callback of a [ForKeys object](../state/forkeys) -encountered an error. - -```Lua -local example = ForKeys(array, function(key) - local badMath = 2 + "fish" -end) -``` -
-
-
------
-
-- since v0.2 -
- -## forPairsDestructorError - -``` -ForPairs destructor error: attempt to index a nil value -``` - -This message means the destructor passed to a [ForPairs object](../state/forpairs) -encountered an error. - -```Lua -local function destructor(x, y) - local badMath = 2 + "fish" -end - -local example = ForPairs(array, doSomething, destructor) -``` -
-
-
------
-
-- since v0.2 -
- -## forPairsKeyCollision - -``` -ForPairs should only write to output key 'Charlie' once when processing key changes, but it wrote to it twice. Previously input key: 'Alice'; New input key: 'Bob' -``` - -This message means you returned the same value twice for two different keys in -a [ForPairs object](../state/forpairs). - -```Lua -local data = { - Alice = true, - Bob = true -} -local example = ForPairs(data, function(key, value) - if key == "Alice" or key == "Bob" then - return "Charlie", value - end -end) -``` -
-
-
------
-
-- since v0.2 -
- -## forPairsProcessorError - -``` -ForPairs callback error: attempt to index a nil value -``` - -This message means the callback of a [ForPairs object](../state/forpairs) -encountered an error. - -```Lua -local example = ForPairs(array, function(key, value) - local badMath = 2 + "fish" -end) -``` -
-
-
------
-
-- since v0.2 -
- -## forValuesDestructorError - -``` -ForValues destructor error: attempt to index a nil value -``` - -This message means the destructor passed to a [ForValues object](../state/forvalues) -encountered an error. - -```Lua -local function destructor(x) - local badMath = 2 + "fish" -end - -local example = ForValues(array, doSomething, destructor) -``` -
-
-
------
-
-- since v0.2 -
- -## forValuesProcessorError - -``` -ForValues callback error: attempt to index a nil value -``` - -This message means the callback of a [ForValues object](../state/forvalues) -encountered an error. - -```Lua -local example = ForValues(array, function(value) - local badMath = 2 + "fish" -end) -``` -
-
-
------
-
-- since v0.2 -
- -## invalidChangeHandler - -``` -The change handler for the 'Text' property must be a function. -``` - -This message means you tried to use [OnChange](../instances/onchange) on an -instance's property, but instead of passing a function callback, you passed -something else. - -```Lua -local input = New "TextBox" { - [OnChange "Text"] = "lemons" -} -``` -
-
- since v0.3 -
- -## invalidAttributeChangeHandler - -``` -The change handler for the 'Ammo' attribute must be a function. -``` - -This message means you tried to use [AttributeChange](../instances/attributechange) on an -instance's attribute, but instead of passing a function callback, you passed -something else. - -```Lua -local config = New "Configuration" { - [AttributeChange "Ammo"] = "guns" -} -``` - ------ - -
-
-
------
-
-- since v0.2 -
- -## invalidEventHandler - -``` -The handler for the 'Activated' event must be a function. -``` - -This message means you tried to use [OnEvent](../instances/onevent) on an -instance's event, but instead of passing a function callback, you passed -something else. - -```Lua -local button = New "TextButton" { - [OnEvent "Activated"] = "limes" -} -``` -
-
-
------
-
-- since v0.2 -
- -## invalidPropertyType - -``` -'Frame.Size' expected a 'UDim2' type, but got a 'Color3' type. -``` - -This message means you tried to set a property on an instance, but you gave it -the wrong type of value. - -This usually occurs with the [New](../instances/new) or -[Hydrate](../instances/hydrate) functions: - -```Lua -local ui = New "Frame" { - Size = Computed(function() - return Color3.new(1, 0, 0) - end) -} -``` -
-
-
------
-
-- since v0.2 -
- -## invalidRefType - -``` -Instance refs must be Value objects. -``` - -This message means you tried to use [Ref](../instances/ref), but you didn't also -give it a [value object](../state/value) to store the instance inside of. - -```Lua -local thing = New "Part" { - [Ref] = 2 -} -``` -
-
-
------
-
-- since v0.2 -
- -## invalidOutType - -``` -[Out] properties must be given Value objects. -``` - -This message means you tried to use [Out](../instances/out), but you didn't also -give it a [value object](../state/value) to store the property's value inside -of. - -```Lua -local thing = New "Part" { - [Out "Color"] = true -} -``` -
-
- since v0.3 -
- -## invalidAttributeOutType - -``` -[AttributeOut] properties must be given Value objects. -``` - -This message means you tried to use [AttributeOut](../instances/attributeout), but you didn't also -give it a [value object](../state/value) to store the attributes's value inside -of. - -```Lua -local config = New "Configuration" { - [AttributeChange "Ammo"] = "guns" -} -``` - ------ - -
-
-
------
-
-- since v0.2 -
- -## invalidOutProperty - -``` -The Part class doesn't have a property called 'Flobulator'. -``` - -This message means you tried to read a property of an instance using -[Out](../instances/out), but the property can't be read. This could be because -the property doesn't exist, or because it's locked by Roblox to prevent reading. - -```Lua -local value = Value() - -local thing = New "Part" { - [Out "Flobulator"] = value -} -``` -
-
- since v0.3 -
- -## invalidAttributeOutName - -``` -The Configuration class doesn't have an attribute called 'Ammo' -``` - -This message means you tried to read an attribute of an instance using -[AttributeOut](../instances/attributeout), but the attribute can't be read. This error -shouldn't occur, however it is here for a failsafe. - -```Lua --- Once again, how does an example for this work? -``` - ------ - -
-
-
------
-
-- since v0.1 -
- -## invalidSpringDamping - -``` -The damping ratio for a spring must be >= 0. (damping was -0.50) -``` - -This message means you gave a damping ratio to a [spring object](../animation/spring) -which is less than 0: - -```Lua -local speed = 10 -local damping = -12345 -local spring = Spring(state, speed, damping) -``` - -Damping ratio must always be between 0 and infinity for a spring to be -physically simulatable. -
-
-
------
-
-- since v0.1 -
- -## invalidSpringSpeed - -``` -The speed of a spring must be >= 0. (speed was -2.00) -``` - -This message means you gave a speed to a [spring object](../animation/spring) -which is less than 0: - -```Lua -local speed = -12345 -local spring = Spring(state, speed) -``` - -Since a speed of 0 is equivalent to a spring that doesn't move, any slower speed -is not simulatable or physically sensible. -
-
-
------
-
-- since v0.1 -
- -## mistypedSpringDamping - -``` -The damping ratio for a spring must be a number. (got a boolean) -``` - -This message means you gave a damping ratio to a [spring object](../animation/spring) -which isn't a number. - -```Lua -local speed = 10 -local damping = true -local spring = Spring(state, speed, damping) -``` -
-
-
------
-
-- since v0.1 -
- -## mistypedSpringSpeed - -``` -The speed of a spring must be a number. (got a boolean) -``` - -This message means you gave a speed to a [spring object](../animation/spring) -which isn't a number. - -```Lua -local speed = true -local spring = Spring(state, speed) -``` -
-
-
------
-
-- since v0.1 -
- -## mistypedTweenInfo - -``` -The tween info of a tween must be a TweenInfo. (got a boolean) -``` - -This message shows if you try to provide a tween info to a [tween](../animation/tween) -which isn't a TweenInfo: - -```Lua -local tweenInfo = true -local tween = Tween(state, tweenInfo) -``` -
-
-
------
-
-- since v0.2 -
- -## multiReturnComputed - -``` -Returning multiple values from Computeds is discouraged, as behaviour will change soon - see discussion #189 on GitHub. -``` - -This message means you returned more than one value from a [computed object](../state/computed). -There are two ways this could occur; either you're explicitly returning two -values (e.g. `return 1, 2`) or you're calling a function which returns two -values (e.g. `string.find`). - -A simple fix is to surround your return expression with parentheses `()`, or to -save it into a variable before returning it. - -[Learn more by visiting this discussion on GitHub.](https://github.com/Elttob/Fusion/discussions/189) - -```Lua -local badComputed = Computed(function() - return 1, 2, "foo", true -end, nil) -``` -
-
- since v0.3 -
- -## noTaskScheduler - -``` -Fusion is not connected to an external task scheduler. -``` - -This message shows when Fusion attempts to schedule something for execution -without first setting a task scheduler for the library to use. - -For users of Fusion on Roblox, this generally shouldn't occur as Fusion should -automatically be bound to Roblox's task scheduler. However, when using Fusion -in other environments, the fix is to provide Fusion with all the task scheduler -callbacks necessary to schedule tasks for execution in the future. - ------ - -
-
-
------
-
-- since v0.2 -
- -## springTypeMismatch - -``` -The type 'number' doesn't match the spring's type 'Color3'. -``` - -Some methods on [spring objects](../animation/spring) require incoming values to -match the types previously being used on the spring. - -This message means you passed a value to one of those methods, but it wasn't the -same type as the type of the spring. - -```Lua -local colour = State(Color3.new(1, 0, 0)) -local colourSpring = Spring(colour) - -colourSpring:addVelocity(Vector2.new(2, 3)) -``` -
-
-
------
-
-- since v0.3 -
- -## stateGetWasRemoved - -``` -`StateObject:get()` has been replaced by `use()` and `peek()` - see discussion #217 on GitHub. -``` - -This message means you attempted to call the now-removed `:get()` method on a -[state object](../state/stateobject.md). Starting with Fusion 0.3, this method -has been removed in favour of the [peek function](../state/peek.md) and -[use callbacks](../state/use.md). - -[Learn more by visiting this discussion on GitHub.](https://github.com/Elttob/Fusion/discussions/217) - -```Lua -local value = Value(5) -print(value:get()) -- should be print(peek(value)) -``` -
-
-
------
-
-- since v0.1 -
- -## strictReadError - -``` -'thisDoesNotExist' is not a valid member of 'Fusion'. -``` - -This message means you tried to access something that doesn't exist. This -specifically occurs with a few 'locked' tables in Fusion, such as the table -returned by the module directly. - -```Lua -local Foo = Fusion.thisDoesNotExist -``` -
-
-
------
-
-- since v0.1 -
- -## unknownMessage - -``` -Unknown error: attempt to index a nil value -``` - -If you see this message, it's almost certainly an internal bug, so make sure to -get in contact so the issue can be fixed. - -When Fusion code attempts to log a message, warning or error, it needs to -provide an ID. This ID is used to show the correct message, and serves as a -simple, memorable identifier if you need to look up the message later. -However, if that code provides an invalid ID, then the message will be replaced -with this one. -
-
-
------
-
-- since v0.1 -
- -## unrecognisedChildType - -``` -'number' type children aren't accepted as children in `New`. -``` - -This message means you tried to pass something to [Children](../instances/children.md) -which isn't a valid [child](../instances/child.md). This usually means that you -passed something that isn't an instance, array or [state object](../state/stateobject.md). - -```Lua -local instance = New "Folder" { - [Children] = { - 1, 2, 3, 4, 5, - - {true, false}, - - State(Enum.Material.Grass) - } -} -``` - -!!! note - Note that state objects are allowed to store `nil` to represent the absence - of an instance, as an exception to these rules. -
-
-
------
-
-- since v0.1 -
- -## unrecognisedPropertyKey - -``` -'number' keys aren't accepted in the property table of `New`. -``` - -This message means, while using [New](../instances/new) or [Hydrate](../instances/hydrate), -you specified something in the property table that's not a property name or -[special key](../instances/specialkey). - -Commonly, this means you accidentally specified children directly inside of -the property table, rather than using the dedicated [Children](../instances/children.md) -special key. - -```Lua -local folder = New "Folder" { - [Vector3.new()] = "Example", - - "This", "Shouldn't", "Be", "Here" -} -``` -
-(
+ defaultValue: T
+): Contextual
+```
+
+Constructs and returns a new [contextual](../../types/contextual).
+
+-----
+
+## Parameters
+
+ = {
+ type: "Contextual",
+ now: (self) -> T,
+ is: (self, newValue: T) -> {
+ during: (self, callback: (A...) -> R, A...) -> R
+ }
+}
+```
+
+An object representing a widely-accessible value, which can take on different
+values at different times in different coroutines.
+
+!!! note "Non-standard type syntax"
+ The above type definition uses `self` to denote methods. At time of writing,
+ Luau does not interpret `self` specially.
+
+-----
+
+## Fields
+
+(
+ self,
+ callback: (A...) -> R,
+ A...
+ ) -> R
+}
+```
+
+Runs the `callback` with the arguments `A...` and returns the value the callback
+returns (`R`). The `Contextual` will appear to be `newValue` in the callback,
+unless it's overridden by another `:is():during()` call.
+
+-----
+
+## Learn More
+
+- [Sharing Values tutorial](../../../../tutorials/best-practices/sharing-values)
\ No newline at end of file
diff --git a/docs/api-reference/general/types/version.md b/docs/api-reference/general/types/version.md
new file mode 100644
index 000000000..5c4385359
--- /dev/null
+++ b/docs/api-reference/general/types/version.md
@@ -0,0 +1,55 @@
+
+
+
- since v0.2 -
- -## unrecognisedPropertyStage - -``` -'discombobulate' isn't a valid stage for a special key to be applied at. -``` - -Fusion provides a standard interface for defining [special keys](../instances/specialkey.md) -which can be used to extend the functionality of [New](../instances/new.md) or -[Hydrate](../instances/hydrate.md). - -Within this interface, keys can select when they run using the `stage` field. -If an unexpected value is passed as the stage, then this error will be thrown -when attempting to use the key. - -```Lua -local Example = { - type = "SpecialKey", - kind = "Example", - stage = "discombobulate", - apply = function() ... end -} - -local folder = New "Folder" { - [Example] = "foo" -} -``` \ No newline at end of file diff --git a/docs/api-reference/general/errors.md b/docs/api-reference/general/errors.md new file mode 100644 index 000000000..d72ae735c --- /dev/null +++ b/docs/api-reference/general/errors.md @@ -0,0 +1,752 @@ + + ++ + Errors +
+ +Whenever Fusion outputs any errors or messages to the console, it will have a +short error ID at the end. This is used to uniquely identify what kind of error +or message you're seeing. + +Use the search box below to paste in or type an error ID, and it will scroll to +the details for you. + + + + + +----- + +
+
+## callbackError
+
+```
+Error in callback: attempt to perform arithmetic (add) on number and string
+```
+
+**Thrown by:**
+[`Computed`](../../state/members/computed),
+[`ForKeys`](../../state/members/forkeys),
+[`ForValues`](../../state/members/forvalues),
+[`ForPairs`](../../state/members/forpairs),
+[`Contextual`](../../memory/members/contextual)
+
+Fusion ran a function you specified, but the function threw an error that Fusion
+couldn't handle.
+
+The error includes a more specific message which can be used to diagnose the
+issue.
+
+
+-----
+
+
+
+## cannotAssignProperty
+
+```
+The class type 'Foo' has no assignable property 'Bar'.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate)
+
+You tried to set a property on an instance, but the property can't be assigned
+to for some reason. This could be because the property doesn't exist, or because
+it's locked by Roblox to prevent edits.
+
+!!! warning "Check your privileges"
+ Different scripts may have different privileges - for example, plugins will
+ be allowed more privileges than in-game scripts. Make sure you have the
+ necessary privileges to assign to your properties!
+
+
+-----
+
+
+
+## cannotConnectChange
+
+```
+The Frame class doesn't have a property called 'Foo'.
+```
+
+**Thrown by:**
+[`OnChange`](../../roblox/members/onchange)
+
+You tried to connect to a property change event, but the property you specify
+doesn't exist on the instance.
+
+
+-----
+
+
+
+## cannotConnectEvent
+
+```
+The Frame class doesn't have an event called 'Foo'.
+```
+
+**Thrown by:**
+[`OnEvent`](../../roblox/members/onevent)
+
+You tried to connect to an event on an instance, but the event you specify
+doesn't exist on the instance.
+
+
+-----
+
+
+
+## cannotCreateClass
+
+```
+Can't create a new instance of class 'EditableImage'.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new)
+
+You attempted to create a type of instance that Fusion can't create.
+
+!!! warning "Beta features"
+ Some instances are only creatable when you have certain Studio betas
+ enabled. Check your Beta Features tab to ensure that beta features aren't
+ causing the issue.
+
+
+-----
+
+
+
+## cleanupWasRenamed
+
+```
+`Fusion.cleanup` was renamed to `Fusion.doCleanup`. This will be an error in
+future versions of Fusion.
+```
+
+**Thrown by:**
+[`doCleanup`](../../memory/members/docleanup)
+
+You attempted to use `cleanup()` in Fusion 0.3, which replaces it with the
+`doCleanup()` method.
+
+
+-----
+
+
+
+## destroyedTwice
+
+```
+Attempted to destroy Computed twice; ensure you're not manually calling
+`:destroy()` while using scopes. See discussion #292 on GitHub for advice.
+```
+
+**Thrown by:**
+[`Value`](../../state/members/value),
+[`Computed`](../../state/members/computed),
+[`Observer`](../../state/members/observer),
+[`ForKeys`](../../state/members/forkeys),
+[`ForValues`](../../state/members/forvalues),
+[`ForPairs`](../../state/members/forpairs),
+[`Spring`](../../animation/members/spring),
+[`Tween`](../../animation/members/tween)
+
+**Related discussions:**
+[`#292`](https://github.com/dphfox/Fusion/discussions/292)
+
+The `:destroy()` method of the object in question was called more than once.
+
+This usually means you called `:destroy()` manually, which is almost never
+required because Fusion's constructors always link objects to
+[scopes](../../../tutorials/fundamentals/scopes). When that scope is passed to
+[`doCleanup()`](../../memory/members/docleanup), the `:destroy()` method is
+called on every object inside.
+
+
+-----
+
+
+
+## destructorRedundant
+
+```
+Computed destructors no longer do anything. If you wish to run code on destroy,
+`table.insert` a function into the `scope` argument. See discussion #292 on
+GitHub for advice.
+```
+
+**Thrown by:**
+[`Computed`](../../state/members/computed),
+[`ForKeys`](../../state/members/forkeys),
+[`ForValues`](../../state/members/forvalues),
+[`ForPairs`](../../state/members/forpairs)
+
+**Related discussions:**
+[`#292`](https://github.com/dphfox/Fusion/discussions/292)
+
+You passed an extra parameter to the constructor, which has historically been
+interpreted as a function that runs when a value is cleaned up.
+
+This mechanism has been replaced by
+[scopes](../../../tutorials/fundamentals/scopes).
+
+
+-----
+
+
+
+## forKeyCollision
+
+```
+The key '6' was returned multiple times simultaneously, which is not allowed in
+`For` objects.
+```
+
+**Thrown by:**
+[`ForKeys`](../../state/members/forkeys),
+[`ForPairs`](../../state/members/forpairs)
+
+When called with different items from the table, the same key was returned for
+both of them. This is not allowed, because keys have to be unique in a table.
+
+
+-----
+
+
+
+## invalidAttributeChangeHandler
+
+```
+The change handler for the 'Active' attribute must be a function.
+```
+
+**Thrown by:**
+[`AttributeChange`](../../roblox/members/attributechange)
+
+`AttributeChange` expected you to provide a function for it to run when the
+attribute changes, but you provided something other than a function.
+
+For example, you might have accidentally provided `nil`.
+
+
+-----
+
+
+
+## invalidAttributeOutType
+
+```
+[AttributeOut] properties must be given Value objects.
+```
+
+**Thrown by:**
+[`AttributeOut`](../../roblox/members/attributeout)
+
+`AttributeOut` expected you to give it a [value](../../state/members/value), but
+you gave it something else.
+
+
+-----
+
+
+
+## invalidChangeHandler
+
+```
+The change handler for the 'AbsoluteSize' property must be a function.
+```
+
+**Thrown by:**
+[`OnChange`](../../roblox/members/onchange)
+
+`OnChange` expected you to provide a function for it to run when the property
+changes, but you provided something other than a function.
+
+For example, you might have accidentally provided `nil`.
+
+
+-----
+
+
+
+## invalidEventHandler
+
+```
+The handler for the 'MouseEnter' event must be a function.
+```
+
+**Thrown by:**
+[`OnEvent`](../../roblox/members/onevent)
+
+`OnEvent` expected you to provide a function for it to run when the event is
+fired, but you provided something other than a function.
+
+For example, you might have accidentally provided `nil`.
+
+
+-----
+
+
+
+## invalidOutProperty
+
+```
+The Frame class doesn't have a property called 'MouseButton1Down'.
+```
+
+**Thrown by:**
+[`Out`](../../roblox/members/out)
+
+The property that you tried to output doesn't exist on the instance that `Out`
+was used with.
+
+
+-----
+
+
+
+## invalidOutType
+
+```
+[Out] properties must be given Value objects.
+```
+
+**Thrown by:**
+[`Out`](../../roblox/members/out)
+
+`Out` expected you to give it a [value](../../state/members/value), but you gave
+it something else.
+
+
+-----
+
+
+
+## invalidPropertyType
+
+```
+'Frame.BackgroundColor3' expected a 'Color3' type, but got a 'Vector3' type.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate)
+
+You attempted to assign a value to a Roblox instance's property, but the
+assignment threw an error because that property doesn't accept values of that
+type.
+
+
+-----
+
+
+
+## invalidRefType
+
+```
+Instance refs must be Value objects.
+```
+
+**Thrown by:**
+[`Ref`](../../roblox/members/ref)
+
+`Ref` expected you to give it a [value](../../state/members/value), but you gave
+it something else.
+
+
+-----
+
+
+
+## invalidSpringDamping
+
+```
+The damping ratio for a spring must be >= 0. (damping was -1.00)
+```
+
+**Thrown by:**
+[`Spring`](../../roblox/members/spring)
+
+You provided a damping ratio that the spring doesn't support, for example `NaN`,
+or a negative damping implying negative friction.
+
+
+-----
+
+
+
+## invalidSpringSpeed
+
+```
+The speed of a spring must be >= 0. (speed was NaN)
+```
+
+**Thrown by:**
+[`Spring`](../../roblox/members/spring)
+
+You provided a speed multiplier that the spring doesn't support, for example
+`NaN` or a negative speed implying the spring moves backwards through time.
+
+
+-----
+
+
+
+## mergeConflict
+
+```
+Multiple definitions for 'Observer' found while merging.
+```
+
+**Thrown by:**
+[`scoped`](../../memory/members/scoped)
+
+Fusion tried to merge together multiple tables, but a key was found in more than
+one of the tables, and it's unclear which one you intended to have in the final
+merged result.
+
+This can happen subtly with methods such as
+[`scoped()`](../../memory/members/scoped) which automatically merge together all
+of their arguments.
+
+
+-----
+
+
+
+## mistypedSpringDamping
+
+```
+The damping ratio for a spring must be a number. (got a string)
+```
+
+**Thrown by:**
+[`Spring`](../../roblox/members/spring)
+
+You provided a damping ratio that the spring couldn't understand. Damping ratio
+has to be a number.
+
+
+-----
+
+
+
+## mistypedSpringSpeed
+
+```
+The speed of a spring must be a number. (got a string)
+```
+
+**Thrown by:**
+[`Spring`](../../roblox/members/spring)
+
+You provided a speed multiplier that the spring couldn't understand. Speed has
+to be a number.
+
+
+-----
+
+
+
+## mistypedTweenInfo
+
+```
+The tween info of a tween must be a TweenInfo. (got a table)
+```
+
+**Thrown by:**
+[`Tween`](../../roblox/members/tween)
+
+You provided an easing curve that the tween couldn't understand. The easing
+curve has to be specified using Roblox's `TweenInfo` data type.
+
+
+-----
+
+
+
+## noTaskScheduler
+
+```
+Fusion is not connected to an external task scheduler.
+```
+
+Fusion depends on a task scheduler being present to perform certain time-related
+tasks such as deferral, delays, or updating animations. You'll need to define a
+set of standard task scheduler functions that Fusion can use for those purposes.
+
+Roblox users should never see this error, as Fusion automatically connects to
+Roblox's task scheduling APIs.
+
+
+-----
+
+
+
+## possiblyOutlives
+
+```
+The Value object could be destroyed before the Computed that is use()-ing it;
+review the order they're created in, and what scopes they belong to. See
+discussion #292 on GitHub for advice.
+```
+
+**Thrown by:**
+[`Spring`](../../animation/members/spring),
+[`Tween`](../../animation/members/tween),
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate),
+[`Attribute`](../../roblox/members/attribute),
+[`AttributeOut`](../../roblox/members/attributeout),
+[`Out`](../../roblox/members/out),
+[`Ref`](../../roblox/members/ref),
+[`Computed`](../../state/members/computed),
+[`Observer`](../../state/members/observer)
+
+**Related discussions:**
+[`#292`](https://github.com/dphfox/Fusion/discussions/292)
+
+If you use an object after it's been destroyed, then your code can break. This
+mainly happens when one object 'outlives' another object that it's using.
+
+Because [scopes](../../../tutorials/fundamentals/scopes) clean up the newest
+objects first, this can happen when an old object depends on something much
+newer that itself. During cleanup, a situation could arise where the newer
+object is destroyed, then the older object runs code of some kind that needed
+the newer object to be there.
+
+Fusion can check for situations like this by analysing the scopes. This message
+is shown when Fusion can prove one of these situations will occur.
+
+There are two typical solutions:
+
+- If the objects should always be created and destroyed at the exact same time,
+then ensure they're created in the correct order.
+- Otherwise, move the objects into separate scopes, and ensure that both scopes
+can exist without the other scope.
+
+
+-----
+
+
+
+## propertySetError
+
+```
+Error setting property: UIAspectRatioConstraint.AspectRatio set to a
+non-positive value. Value must be a positive.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate)
+
+You attempted to set a property, but Roblox threw an error in response.
+
+The error includes a more specific message which can be used to diagnose the
+issue.
+
+
+-----
+
+
+
+## scopeMissing
+
+```
+To create Observers, provide a scope. (e.g. `myScope:Observer(watching)`). See
+discussion #292 on GitHub for advice.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate),
+[`Value`](../../state/members/value),
+[`Computed`](../../state/members/computed),
+[`Observer`](../../state/members/observer),
+[`ForKeys`](../../state/members/forkeys),
+[`ForValues`](../../state/members/forvalues),
+[`ForPairs`](../../state/members/forpairs),
+[`Spring`](../../animation/members/spring),
+[`Tween`](../../animation/members/tween)
+
+**Related discussions:**
+[`#292`](https://github.com/dphfox/Fusion/discussions/292)
+
+You attempted to create an object without providing a
+[scope](../../../tutorials/fundamentals/scopes) as the first parameter.
+
+Scopes are mandatory for all Fusion constructors so that Fusion knows when the
+object should be destroyed.
+
+
+-----
+
+
+
+## springTypeMismatch
+
+```
+The type 'Vector3' doesn't match the spring's type 'Color3'.
+```
+
+**Thrown by:**
+[`Spring`](../../animation/members/spring)
+
+The spring expected you to provide a type matching the data type that the spring
+is currently outputting. However, you provided a different data type.
+
+
+-----
+
+
+
+## stateGetWasRemoved
+
+```
+`StateObject:get()` has been replaced by `use()` and `peek()` - see discussion
+#217 on GitHub.
+```
+
+**Thrown by:**
+[`Value`](../../state/members/value),
+[`Computed`](../../state/members/computed),
+[`ForKeys`](../../state/members/forkeys),
+[`ForValues`](../../state/members/forvalues),
+[`ForPairs`](../../state/members/forpairs),
+[`Spring`](../../animation/members/spring),
+[`Tween`](../../animation/members/tween)
+
+**Related discussions:**
+[`#217`](https://github.com/dphfox/Fusion/discussions/217)
+
+Older versions of Fusion let you call `:get()` directly on state objects to read
+their current value and attempt to infer dependencies.
+
+This has been replaced by [use functions](../../state/types/use) in Fusion 0.3
+for more predictable behaviour and better support for constant values.
+
+
+-----
+
+
+
+## unknownMessage
+
+```
+Unknown error: attempt to call a nil value
+```
+
+Fusion ran into a problem, but couldn't associate it with a valid type of error.
+This is a fallback error type which shouldn't be seen by end users, because it
+indicates that Fusion code isn't reporting errors correctly.
+
+
+-----
+
+
+
+## unrecognisedChildType
+
+```
+'string' type children aren't accepted by `[Children]`.
+```
+
+**Thrown by:**
+[`Children`](../../roblox/members/children)
+
+You provided a value inside of `[Children]` which didn't meet the definition of
+a [child](../../roblox/types/child) value. Check that you're only passing
+instances, arrays and state objects.
+
+
+-----
+
+
+
+## unrecognisedPropertyKey
+
+```
+'number' keys aren't accepted in property tables.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate)
+
+You provided something other than a property assignment (`Property = Value`) or
+[special key](../../roblox/types/specialkey) in your property table.
+
+Most commonly, this means you tried to add child instances directly into the
+property table, rather than passing them into the
+[`[Children]`](../../roblox/members/children) special key.
+
+
+
+-----
+
+
+
+## unrecognisedPropertyStage
+
+```
+'children' isn't a valid stage for a special key to be applied at.
+```
+
+**Thrown by:**
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate)
+
+You attempted to use a [special key](../../roblox/types/specialkey) which has a
+misconfigured `stage`, so Fusion didn't know when to apply it during instance
+construction.
+
+
+-----
+
+
+
+## useAfterDestroy
+
+```
+The Value object is no longer valid - it was destroyed before the Computed that
+is use()-ing. See discussion #292 on GitHub for advice.
+```
+
+**Thrown by:**
+[`Spring`](../../animation/members/spring),
+[`Tween`](../../animation/members/tween),
+[`New`](../../roblox/members/new),
+[`Hydrate`](../../roblox/members/hydrate),
+[`Attribute`](../../roblox/members/attribute),
+[`AttributeOut`](../../roblox/members/attributeout),
+[`Out`](../../roblox/members/out),
+[`Ref`](../../roblox/members/ref),
+[`Computed`](../../state/members/computed),
+[`Observer`](../../state/members/observer)
+
+**Related discussions:**
+[`#292`](https://github.com/dphfox/Fusion/discussions/292)
+
+Your code attempted to access an object after that object was destroyed, either
+because its `:destroy()` method was called manually, or because the object's
+[scope](../../../tutorials/fundamentals/scope) was cleaned up.
+
+Make sure your objects are being added to the correct scopes according to when
+you expect them to be destroyed. Additionally, make sure your code can detect
+and deal with situations where other objects are no longer available.
+
diff --git a/docs/api-reference/general/members/contextual.md b/docs/api-reference/general/members/contextual.md
new file mode 100644
index 000000000..089f04819
--- /dev/null
+++ b/docs/api-reference/general/members/contextual.md
@@ -0,0 +1,52 @@
+
+
++ + Contextual + + -> Contextual<T> + +
+ +```Lua +function Fusion.Contextual+ defaultValue + + : T + +
+ +The value which `Contextual:now()` should return if no value has been specified +by `Contextual:is():during()`. + +----- + ++ Returns + + -> Contextual<T> + +
+ +A freshly constructed contextual. + +----- + +## Learn More + +- [Sharing Values tutorial](../../../../tutorials/best-practices/sharing-values) \ No newline at end of file diff --git a/docs/api-reference/general/members/version.md b/docs/api-reference/general/members/version.md new file mode 100644 index 000000000..aa8ba3d0d --- /dev/null +++ b/docs/api-reference/general/members/version.md @@ -0,0 +1,22 @@ + + ++ + version + + : Version + +
+ +```Lua +Fusion.version: Version +``` + +The version of the Fusion source code. + +`isRelease` is only `true` when using a version of Fusion downloaded from +[the Releases page](https://github.com/dphfox/Fusion/releases). \ No newline at end of file diff --git a/docs/api-reference/general/types/contextual.md b/docs/api-reference/general/types/contextual.md new file mode 100644 index 000000000..0053f9a50 --- /dev/null +++ b/docs/api-reference/general/types/contextual.md @@ -0,0 +1,87 @@ + + ++ + Contextual +
+ +```Lua +export type Contextual+ type + + : "Contextual" + +
+ +A type string which can be used for runtime type checking. + +----- + +## Methods + ++ now + + -> T + +
+ +```Lua +function Contextual:now(): T +``` + +Returns the current value of this contextual. This varies based on when the +function is called, and in what coroutine it was called. + ++ is/during + + -> R + +
+ +```Lua +function Contextual:is( + newValue: T +): { + during:+ + Version +
+ +```Lua +export type Version = { + major: number, + minor: number, + isRelease: boolean +} +``` + +Describes a version of Fusion's source code. + +----- + +## Members + ++ major + + : number + +
+ +The major version number. If this is greater than `0`, then two versions sharing +the same major version number are not expected to be incompatible or have +breaking changes. + ++ minor + + : number + +
+ +The minor version number. Describes version updates that are not enumerated by +the major version number, such as versions prior to 1.0, or versions which +are non-breaking. + ++ isRelease + + : boolean + +
+ +Describes whether the version was sourced from an official release package. \ No newline at end of file diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md index d70204fe9..c2c1756f5 100644 --- a/docs/api-reference/index.md +++ b/docs/api-reference/index.md @@ -7,113 +7,122 @@ title: API Reference Welcome to the API Reference! This is where you can find more technical documentation about what the Fusion library provides. -This isn't a beginner's guide. For a guided experience, [try the tutorials!](../tutorials/) +For a beginner-friendly experience, [try the tutorials.](../tutorials/) ------ +## Most Popular -## Navigation +
-Using the sidebar on the left, you can find API members grouped by category.
-Alternatively, you can search for APIs using the search box at the top of the
-page.
-
------
-
-## Commonly Used
-
-
-
-
+
### General
-
+
Errors
:octicons-chevron-right-24:
-
-
-
- State
+
+
+ Contextual
:octicons-chevron-right-24:
+
-
-
- Instances
+
+### Memory
+
+
+ Scope
:octicons-chevron-right-24:
-
-
-
- Animation
+
+
+ deriveScope
+ :octicons-chevron-right-24:
+
+
+
+ doCleanup
+ :octicons-chevron-right-24:
+
+
+
+ scoped
:octicons-chevron-right-24:
-
+
### State
-
-
- Computed
+
+
+ CanBeState
:octicons-chevron-right-24:
-
-
-
- ForKeys
+
+
+ StateObject
:octicons-chevron-right-24:
-
-
-
- ForPairs
+
+
+ Computed
:octicons-chevron-right-24:
-
-
-
- ForValues
+
+
+ Observer
:octicons-chevron-right-24:
-
-
-
- Observer
+
+
+ peek
:octicons-chevron-right-24:
-
-
-
+
+
Value
:octicons-chevron-right-24:
-
-### Instances
-
-
+
+### Roblox
+
+
+ Child
+ :octicons-chevron-right-24:
+
+
+
+ Children
+ :octicons-chevron-right-24:
+
+
+
Hydrate
:octicons-chevron-right-24:
-
-
-
+
+
New
:octicons-chevron-right-24:
-
+
### Animation
-
-
+
+
+ Animatable
+ :octicons-chevron-right-24:
+
+
+
Spring
:octicons-chevron-right-24:
-
-
-
+
+
Tween
:octicons-chevron-right-24:
diff --git a/docs/api-reference/instances/attribute.md b/docs/api-reference/instances/attribute.md
deleted file mode 100644
index cc0dea384..000000000
--- a/docs/api-reference/instances/attribute.md
+++ /dev/null
@@ -1,44 +0,0 @@
-
-
-
-```
-
------
-
-## Example Usage
-
-```Lua
--- all of the following fit the definition of Child
-
-local child1: Child = New "Folder" {}
-local child2: Child = {
- New "Folder" {},
- New "Folder" {},
- New "Folder" {}
-}
-local child3: Child = Computed(function()
- return New "Folder" {}
-end)
-local child4: Child = {
- Computed(function()
- return New "Folder" {}
- end),
- {New "Folder" {}, New "Folder" {}}
-}
-```
\ No newline at end of file
diff --git a/docs/api-reference/instances/children.md b/docs/api-reference/instances/children.md
deleted file mode 100644
index 6c64fe7d8..000000000
--- a/docs/api-reference/instances/children.md
+++ /dev/null
@@ -1,127 +0,0 @@
-
-
-(
+ existing: Scope
+): Scope
+```
+
+Returns a blank [scope](../../types/scope) with the same methods as an existing
+scope.
+
+!!! warning "Scopes are not unique"
+ Fusion can recycle old unused scopes. This helps make scopes more
+ lightweight, but it also means they don't uniquely belong to any part of
+ your program.
+
+ As a result, you shouldn't hold on to scopes after they've been cleaned up,
+ and you shouldn't use them as unique identifiers anywhere.
+
+-----
+
+## Parameters
+
+(
+ constructors: T
+): Scope
+```
+
+Returns a blank [scope](../../types/scope), with the `__index` metatable
+pointing at the given list of constructors for syntax convenience.
+
+!!! warning "Scopes are not unique"
+ Fusion can recycle old unused scopes. This helps make scopes more
+ lightweight, but it also means they don't uniquely belong to any part of
+ your program.
+
+ As a result, you shouldn't hold on to scopes after they've been cleaned up,
+ and you shouldn't use them as unique identifiers anywhere.
+
+-----
+
+## Parameters
+
+ = {unknown} & Constructors
+```
+
+A table collecting all objects created as part of an independent unit of code,
+with optional `Constructors` as methods which can be called.
+
+!!! warning "Scopes are not unique"
+ Fusion can recycle old unused scopes. This helps make scopes more
+ lightweight, but it also means they don't uniquely belong to any part of
+ your program.
+
+ As a result, you shouldn't hold on to scopes after they've been cleaned up,
+ and you shouldn't use them as unique identifiers anywhere.
+
+-----
+
+## Learn More
+
+- [Scopes tutorial](../../../../tutorials/fundamentals/scopes)
\ No newline at end of file
diff --git a/docs/api-reference/memory/types/scopedobject.md b/docs/api-reference/memory/types/scopedobject.md
new file mode 100644
index 000000000..d2f995ebf
--- /dev/null
+++ b/docs/api-reference/memory/types/scopedobject.md
@@ -0,0 +1,78 @@
+
+
+?,
+ destroy: () -> ()
+}
+```
+
+An object designed for use with [scopes](../../types/scope).
+
+Objects satisfying this interface can be probed for information about their
+lifetime and how long they live relative to other objects satisfying this
+interface.
+
+These objects are also recognised by [`doCleanup`](../../members/docleanup).
+
+-----
+
+## Members
+
+ | {[unknown]: Child}
+```
+
+All of the types understood by the [`[Children]`](../../members/children)
+special key.
+
+-----
+
+## Learn More
+
+- [Parenting tutorial](../../../../tutorials/roblox/parenting/)
+- [Instance Handling tutorial](../../../../tutorials/best-practices/instance-handling/)
\ No newline at end of file
diff --git a/docs/api-reference/roblox/types/propertytable.md b/docs/api-reference/roblox/types/propertytable.md
new file mode 100644
index 000000000..d3fc62bcc
--- /dev/null
+++ b/docs/api-reference/roblox/types/propertytable.md
@@ -0,0 +1,25 @@
+
+
+,
+ value: unknown,
+ applyTo: Instance
+ ) -> ()
+}
+```
+
+When used as the key in a [property table](../propertytable), defines a custom
+operation to apply to the created Roblox instance.
+
+!!! note "Non-standard type syntax"
+ The above type definition uses `self` to denote methods. At time of writing,
+ Luau does not interpret `self` specially.
+
+-----
+
+## Members
+
+,
+ value: unknown,
+ applyTo: Instance
+): ()
+```
+
+Called to apply this operation to an instance. `value` is the value from the
+property table, and `applyTo` is the instance to apply the operation to.
+
+The given `scope` is cleaned up when the operation is being unapplied, including
+when the instance is destroyed. Operations should use the scope to clean up any
+connections or undo any changes they cause.
\ No newline at end of file
diff --git a/docs/api-reference/state/canbestate.md b/docs/api-reference/state/canbestate.md
deleted file mode 100644
index 9b2b36372..000000000
--- a/docs/api-reference/state/canbestate.md
+++ /dev/null
@@ -1,44 +0,0 @@
-
-
- | T
-```
-
------
-
-## Example Usage
-
-```Lua
-local function printItem(item: CanBeState)
- if typeof(item) == "string" then
- -- constant
- print("Got constant: ", item)
- else
- -- state object
- print("Got state object: ", peek(item))
- end
-end
-
-local constant = "Hello"
-local state = Value("World")
-
-printItem(constant) --> Got constant: Hello
-printItem(state) --> Got state object: World
-```
\ No newline at end of file
diff --git a/docs/api-reference/state/cleanup.md b/docs/api-reference/state/cleanup.md
deleted file mode 100644
index ccde7d676..000000000
--- a/docs/api-reference/state/cleanup.md
+++ /dev/null
@@ -1,53 +0,0 @@
-
-
-
-```
-
------
-
-## Parameters
-
-- `processor: (Use) -> (T, M)` - computes and returns values to be returned from
-the computed object, optionally returning extra values for the destructor alone
-
-- `destructor: ((T, M) -> ())?` - disposes of values generated by `processor`
-when they are no longer in use
-
------
-
-## Example Usage
-
-```Lua
-local numCoins = Value(50)
-
-local doubleCoins = Computed(function(use)
- return use(numCoins) * 2
-end)
-
-print(peek(doubleCoins)) --> 100
-
-numCoins:set(2)
-print(peek(doubleCoins)) --> 4
-```
-
------
-
-## Dependency Management
-
-By default, computed objects run their processor function once during
-construction, then cache the result indefinitely. To specify the calculation
-should re-run when a state object changes value, the objects can be passed
-to the [use callback](./use.md) passed to the processor function. The use
-callback will unwrap the value as normal, but any state objects will become
-dependencies of the computed object.
-
------
-
-## Destructors
-
-The `destructor` callback, if provided, is called when the computed object swaps
-out an old value for a newly-generated one. It is called with the old value as
-the first parameter, and - if provided - an extra value returned from `processor`
-as a customisable second parameter.
-
-Destructors are required when working with data types that require destruction,
-such as instances. Otherwise, they are optional, so not all calculations have to
-specify destruction behaviour.
-
-Fusion guarantees that values passed to destructors by default will never be
-used again by the library, so it is safe to finalise them. This does not apply
-to the customisable second parameter, which the user is responsible for handling
-properly.
\ No newline at end of file
diff --git a/docs/api-reference/state/dependency.md b/docs/api-reference/state/dependency.md
deleted file mode 100644
index f500c05b2..000000000
--- a/docs/api-reference/state/dependency.md
+++ /dev/null
@@ -1,40 +0,0 @@
-
-
-
-}
-```
-
------
-
-## Example Usage
-
-```Lua
--- these are examples of objects which are dependencies
-local value: Dependency = Value(2)
-local computed: Dependency = Computed(function(use)
- return use(value) * 2
-end)
-
--- dependencies can be used with some internal functions such as updateAll()
-updateAll(value)
-```
\ No newline at end of file
diff --git a/docs/api-reference/state/dependent.md b/docs/api-reference/state/dependent.md
deleted file mode 100644
index 507c8ecf3..000000000
--- a/docs/api-reference/state/dependent.md
+++ /dev/null
@@ -1,66 +0,0 @@
-
-
-,
- update: (self) -> boolean
-}
-```
-
------
-
-## Fields
-
-- `dependencySet` - stores the graph objects which this object can receive
-updates from
-
------
-
-## Methods
-
-
-```
-
------
-
-## Parameters
-
-- `input: CanBeState<{[KI]: V}>` - the table to be processed, either as a state
-object or a constant value
-- `keyProcessor: (Use, KI) -> (KO, M)` - transforms input keys into new
-keys, optionally providing metadata for the destructor alone
-- `keyDestructor: ((KO, M) -> ())?` - disposes of values generated by
-`keyProcessor` when they are no longer in use
-
------
-
-## Example Usage
-
-```Lua
-local data = Value({
- one = 1,
- two = 2,
- three = 3,
- four = 4
-})
-
-local transformed = ForKeys(data, function(use, key)
- local newKey = string.upper(key)
- return newKey
-end)
-
-print(peek(transformed)) --> {ONE = 1, TWO = 2 ... }
-```
-
------
-
-## Dependency Management
-
-By default, ForKeys runs the processor function once per key in the input, then
-caches the result indefinitely. To specify the calculation should re-run for the
-key when a state object changes value, the objects can be passed to the
-[use callback](./use.md) passed to the processor function for that key. The use
-callback will unwrap the value as normal, but any state objects will become
-dependencies of that key.
-
------
-
-## Destructors
-
-The `keyDestructor` callback, if provided, is called when this object swaps out
-an old key for a newly-generated one. It is called with the old key as the first
-parameter, and - if provided - an extra value returned from `keyProcessor` as a
-customisable second parameter.
-
-Destructors are required when working with data types that require destruction,
-such as instances. Otherwise, they are optional, so not all calculations have to
-specify destruction behaviour.
-
-Fusion guarantees that values passed to destructors by default will never be
-used again by the library, so it is safe to finalise them. This does not apply
-to the customisable second parameter, which the user is responsible for handling
-properly.
-
------
-
-## Optimisations
-
-ForKeys does not allow access to the values of the input table. This guarantees
-that all generated keys are completely independent of any values. This means
-keys only need to be calculated when they're added to the input table - all
-other changes are simply forwarded to the output table. Since keys are also
-unique, all calculations are unique, so caching and reuse are not required.
\ No newline at end of file
diff --git a/docs/api-reference/state/forpairs.md b/docs/api-reference/state/forpairs.md
deleted file mode 100644
index 704ba3a9d..000000000
--- a/docs/api-reference/state/forpairs.md
+++ /dev/null
@@ -1,98 +0,0 @@
-
-
-
-```
-
------
-
-## Parameters
-
-- `input: CanBeState<{[KI]: VI}>` - the table to be processed, either as a state
-object or a constant value
-- `pairProcessor: (Use, KI, VI) -> (KO, VO, M)` - transforms input key-value
-pairs into new key-value pairs, optionally providing metadata for the destructor
-alone
-- `pairDestructor: ((KO, VO, M) -> ())?` - disposes of values generated by
-`pairProcessor` when they are no longer in use
-
------
-
-## Example Usage
-
-```Lua
-local data = Value({
- one = 1,
- two = 2,
- three = 3,
- four = 4
-})
-
-local transformed = ForPairs(data, function(use, key, value)
- local newKey = value
- local newValue = string.upper(key)
- return newKey, newValue
-end)
-
-print(peek(transformed)) --> {[1] = "ONE", [2] = "TWO" ... }
-```
-
------
-
-## Dependency Management
-
-By default, ForPairs runs the processor function once per key/value pair in the
-input, then caches the result indefinitely. To specify the calculation should
-re-run for the key/value pair when a state object changes value, the objects can
-be passed to the [use callback](./use.md) passed to the processor function for
-that key/value pair. The use callback will unwrap the value as normal, but any
-state objects will become dependencies of that key/value pair.
-
------
-
-## Destructors
-
-The `pairDestructor` callback, if provided, is called when this object swaps
-out an old key-value pair for a newly-generated one. It is called with the old
-pair as the first and second parameters, and - if provided - an extra value
-returned from `pairProcessor` as a customisable third parameter.
-
-Destructors are required when working with data types that require destruction,
-such as instances. Otherwise, they are optional, so not all calculations have to
-specify destruction behaviour.
-
-Fusion guarantees that values passed to destructors by default will never be
-used again by the library, so it is safe to finalise them. This does not apply
-to the customisable third parameter, which the user is responsible for handling
-properly.
-
------
-
-## Optimisations
-
-ForPairs is the least restrictive of the For objects, allowing full access to
-the key-value pairs being processed. This means that very little optimisation is
-applied - values are always locked to the specific key they were generated for,
-and any change in the input's key or value will prompt a recalculation.
-
-For other optimisations, consider using [ForValues](../forvalues) or
-[ForKeys](../forkeys), which impose stricter restrictions to allow for less
-frequent updates and greater reuse.
\ No newline at end of file
diff --git a/docs/api-reference/state/forvalues.md b/docs/api-reference/state/forvalues.md
deleted file mode 100644
index b815a1bec..000000000
--- a/docs/api-reference/state/forvalues.md
+++ /dev/null
@@ -1,93 +0,0 @@
-
-
-
-```
-
------
-
-## Parameters
-
-- `input: CanBeState<{[K]: VI}>` - the table to be processed, either as a state
-object or a constant value
-- `valueProcessor: (Use, VI) -> (VO, M)` - transforms input values into new values,
-optionally providing metadata for the destructor alone
-- `valueDestructor: ((VO, M) -> ())?` - disposes of values generated by
-`valueProcessor` when they are no longer in use
-
------
-
-## Example Usage
-
-```Lua
-local data = Value({
- one = 1,
- two = 2,
- three = 3,
- four = 4
-})
-
-local transformed = ForValues(data, function(use, value)
- local newValue = value * 2
- return newValue
-end)
-
-print(peek(transformed)) --> {ONE = 2, TWO = 4 ... }
-```
-
------
-
-## Dependency Management
-
-By default, ForValues runs the processor function once per value in the input,
-then caches the result indefinitely. To specify the calculation should re-run
-for the value when a state object changes value, the objects can be passed to
-the [use callback](./use.md) passed to the processor function for that value.
-The use callback will unwrap the value as normal, but any state objects will
-become dependencies of that value.
-
------
-
-## Destructors
-
-The `valueDestructor` callback, if provided, is called when this object swaps
-out an old value for a newly-generated one. It is called with the old value as
-the first parameter, and - if provided - an extra value returned from
-`valueProcessor` as a customisable second parameter.
-
-Destructors are required when working with data types that require destruction,
-such as instances. Otherwise, they are optional, so not all calculations have to
-specify destruction behaviour.
-
-Fusion guarantees that values passed to destructors by default will never be
-used again by the library, so it is safe to finalise them. This does not apply
-to the customisable second parameter, which the user is responsible for handling
-properly.
-
------
-
-## Optimisations
-
-ForValues does not allow access to the keys of the input table. This guarantees
-that all generated values are completely independent of the key they were
-generated for. This means that values may be moved between keys instead of being
-destroyed when their original key changes value. Values are only reused once -
-values aren't copied when there are multiple occurences of the same input.
\ No newline at end of file
diff --git a/docs/api-reference/state/index.md b/docs/api-reference/state/index.md
deleted file mode 100644
index 3c898f685..000000000
--- a/docs/api-reference/state/index.md
+++ /dev/null
@@ -1,112 +0,0 @@
-
-
-(
+ scope: Scope,
+ processor: (Use, Scope) -> T
+) -> Computed
+```
+
+Constructs and returns a new [computed state object](../../types/computed).
+
+!!! success "Use scoped() method syntax"
+ This function is intended to be accessed as a method on a scope:
+ ```Lua
+ local computed = scope:Computed(processor)
+ ```
+
+-----
+
+## Parameters
+
+(
+ scope: Scope,
+ inputTable: CanBeState<{[KI]: V}>,
+ processor: (Use, Scope, key: KI) -> KO
+) -> For
+```
+
+Constructs and returns a new [For state object](../../types/for) which processes
+keys and preserves values.
+
+!!! success "Use scoped() method syntax"
+ This function is intended to be accessed as a method on a scope:
+ ```Lua
+ local forObj = scope:ForKeys(inputTable, processor)
+ ```
+
+-----
+
+## Parameters
+
+(
+ scope: Scope,
+ inputTable: CanBeState<{[KI]: VI}>,
+ processor: (Use, Scope, key: KI, value: VI) -> (KO, VO)
+) -> For
+```
+
+Constructs and returns a new [For state object](../../types/for) which processes
+keys and values in pairs.
+
+!!! success "Use scoped() method syntax"
+ This function is intended to be accessed as a method on a scope:
+ ```Lua
+ local forObj = scope:ForPairs(inputTable, processor)
+ ```
+
+-----
+
+## Parameters
+
+(
+ scope: Scope,
+ inputTable: CanBeState<{[K]: VI}>,
+ processor: (Use, Scope, value: VI) -> VO
+) -> For
+```
+
+Constructs and returns a new [For state object](../../types/for) which processes
+values and preserves keys.
+
+!!! success "Use scoped() method syntax"
+ This function is intended to be accessed as a method on a scope:
+ ```Lua
+ local forObj = scope:ForValues(inputTable, processor)
+ ```
+
+-----
+
+## Parameters
+
+,
+ watching: Dependency
+) -> Observer
+```
+
+Constructs and returns a new [observer](../../types/observer).
+
+!!! success "Use scoped() method syntax"
+ This function is intended to be accessed as a method on a scope:
+ ```Lua
+ local observer = scope:Observer(watching)
+ ```
+
+-----
+
+## Parameters
+
+(
+ target: CanBeState
+): T
+```
+
+Extract a value of type `T` from its input.
+
+This is a general-purpose implementation of [`Use`](../../types/use). It does
+not do any extra processing or book-keeping beyond what is required to determine
+the returned value.
+
+!!! warning "Specific implementations"
+ If you're given a specific implementation of `Use` by an API, it's highly
+ likely that you are expected to use that implementation instead of `peek()`.
+
+ This applies to reusable code too. It's often best to ask for a `Use`
+ callback if your code needs to extract values, so an appropriate
+ implementation can be passed in.
+
+ Alternatively for reusable code, you can avoid extracting values entirely,
+ and expect the user to do it prior to calling your code. This can work well
+ if you unconditionally use all inputs, but beware that you may end up
+ extracting more values than you need - this can have performance
+ implications.
+
+-----
+
+## Parameters
+
+(
+ scope: Scope,
+ initialValue: T
+) -> Value
+```
+
+Constructs and returns a new [value state object](../../types/value).
+
+!!! success "Use scoped() method syntax"
+ This function is intended to be accessed as a method on a scope:
+ ```Lua
+ local computed = scope:Computed(processor)
+ ```
+
+-----
+
+## Parameters
+
+(target: CanBeState) -> T
-```
-
------
-
-## Parameters
-
-- `target: CanBeState` - The argument to attempt to unwrap.
-
------
-
-## Returns
-
-If the argument is a state object, returns the interior value of the state
-object. Otherwise, returns the argument itself.
-
------
-
-## Example Usage
-
-```Lua
-local thing = Value(5)
-
-print(peek(thing)) --> 5
-```
\ No newline at end of file
diff --git a/docs/api-reference/state/stateobject.md b/docs/api-reference/state/stateobject.md
deleted file mode 100644
index daa3fc1c7..000000000
--- a/docs/api-reference/state/stateobject.md
+++ /dev/null
@@ -1,46 +0,0 @@
-
-
- = T | StateObject
+```
+
+Something which describes a value of type `T`. When it is [used](../use) in a
+calculation, it becomes that value.
+
+!!! success "Recommended"
+ Instead of using one of the more specific variants, your code should aim to
+ use this type as often as possible. It allows your logic to deal with many
+ representations of values at once,
+
+-----
+
+## Variants
+
+- `T` - represents unchanging constant values
+- [`StateObject`](../stateobject) - represents dynamically updating values
+
+-----
+
+## Learn More
+
+- [Components tutorial](../../../../tutorials/best-practices/components/)
\ No newline at end of file
diff --git a/docs/api-reference/state/types/computed.md b/docs/api-reference/state/types/computed.md
new file mode 100644
index 000000000..c6d81f297
--- /dev/null
+++ b/docs/api-reference/state/types/computed.md
@@ -0,0 +1,45 @@
+
+
+ = StateObject & Dependent & {
+ kind: "Computed"
+}
+```
+
+A specialised [state object](../stateobject) for tracking single values computed
+from a user-defined computation.
+
+In addition to the standard state object interfaces, this object is a
+[dependent](../dependent) so it can receive updates from the objects used as
+part of the computation.
+
+This type isn't generally useful outside of Fusion itself.
+
+-----
+
+## Members
+
+ = StateObject<{[KO]: VO}> & Dependent & {
+ kind: "For"
+}
+```
+
+A specialised [state object](../stateobject) for tracking multiple values
+computed from user-defined computations, which are merged into an output table.
+
+In addition to the standard state object interfaces, this object is a
+[dependent](../dependent) so it can receive updates from objects used as
+part of any of the computations.
+
+This type isn't generally useful outside of Fusion itself.
+
+-----
+
+## Members
+
+ = Dependency & {
+ type: "State",
+ kind: string
+}
+```
+
+Stores a value of `T` which can change over time. As a
+[dependency](../dependency), it can broadcast updates when its value changes.
+
+This type isn't generally useful outside of Fusion itself; you should prefer to
+work with [`CanBeState`](../canbestate) in your own code.
+
+-----
+
+## Members
+
+(target: CanBeState) -> T
+```
+
+A function which extracts a value of `T` from abstract representations of `T`
+([`CanBeState`](../canbestate)).
+
+The most generic implementation of this is
+[the `peek()` function](../../members/peek), which performs this extraction with
+no additional steps.
+
+However, certain APIs may provide their own implementation,
+so they can perform additional processing for certain representations. Most
+notably, [computeds](../../members/computed) provide their own `use()` function
+which adds inputs to a watchlist, which allows them to re-calculate as inputs
+change.
+
+-----
+
+## Parameters
+
+ = StateObject & {
+ kind: "State",
+ set: (self, newValue: T) -> ()
+}
+```
+
+A specialised [state object](../stateobject) which allows regular Luau code to
+control its value.
+
+!!! note "Non-standard type syntax"
+ The above type definition uses `self` to denote methods. At time of writing,
+ Luau does not interpret `self` specially.
+
+-----
+
+## Members
+
+(target: CanBeState) -> T
-```
-
------
-
-## Example Usage
-
-```Lua
-local foo: Value = Value(2)
-local doubleFoo = Computed(function(use: Fusion.Use)
- return use(foo) * 2
-end)
-```
\ No newline at end of file
diff --git a/docs/api-reference/state/value.md b/docs/api-reference/state/value.md
deleted file mode 100644
index 1db40e04c..000000000
--- a/docs/api-reference/state/value.md
+++ /dev/null
@@ -1,84 +0,0 @@
-
-
-
-```
-
------
-
-## Parameters
-
-- `initialValue` - The value that should be initially stored after construction.
-
------
-
-## Methods
-
-
- - Attribute - - special key - since v0.3 - -
- -A [special key](./specialkey.md) for adding attributes to instances. - ------ - -## Parameters - -```lua -(attributeName: string) -> SpecialKey -``` - ------ - -## Example Usage - -```lua -local ammoValue = Value(10) -local label = New "TextLabel" { - [Attribute "Ammo"] = ammoValue -} - -print(label:GetAttribute("Ammo")) -- 10 -``` - ------ - -## Technical Details - -This special key runs at the `self` stage. - ------ diff --git a/docs/api-reference/instances/attributechange.md b/docs/api-reference/instances/attributechange.md deleted file mode 100644 index 7d4ba3e3c..000000000 --- a/docs/api-reference/instances/attributechange.md +++ /dev/null @@ -1,46 +0,0 @@ - - -- - AttributeChange - - function - since v0.3 - -
- -Given an attribute name, returns a [special key](./specialkey.md) which connects -to that attribute's change events. - -```Lua -(attributeName: string) -> SpecialKey -``` - ------ - -## Parameters - -- `attributeName` - The name of the attribute to listen for changes to. - ------ - -## Returns - -A special key which runs at the `observer` stage. When applied to an instance, -it connects to the attribute change signal on the instance for the given property. -The handler is run with the attribute's value after every change. - ------ - -## Example Usage - -```Lua -New "TextBox" { - [AttributeChange "State"] = function(newValue) - print("The state attribute changed to:", newValue) - end -} -``` diff --git a/docs/api-reference/instances/attributeout.md b/docs/api-reference/instances/attributeout.md deleted file mode 100644 index 5532c3012..000000000 --- a/docs/api-reference/instances/attributeout.md +++ /dev/null @@ -1,51 +0,0 @@ - - -- - AttributeOut - - function - since v0.3 - -
- -Given an attribute name, returns a [special key](./specialkey.md) which outputs the value of -attribute's with that name. It should be used with a [value](../state/value.md) object. - -```Lua -(attributeName: string) -> SpecialKey -``` - ------ - -## Parameters - -- `attributeName` - The name of the attribute to output the value of. - ------ - -## Returns - -A special key which runs at the `observer` stage. When applied to an instance, -it sets the value object equal to the attribute with the given name. It then -listens for further changes and updates the value object accordingly. - ------ - -## Example Usage - -```Lua -local ammo = Value() - -New "Configuration" { - [Attribute "Ammo"] = ammo, - [AttributeOut "Ammo"] = ammo -} - -Observer(ammo):onChange(function() - print("Current ammo:", peek(ammo)) -end) -``` diff --git a/docs/api-reference/instances/child.md b/docs/api-reference/instances/child.md deleted file mode 100644 index db1a358f7..000000000 --- a/docs/api-reference/instances/child.md +++ /dev/null @@ -1,46 +0,0 @@ - - -- - Child - - type - since v0.2 - -
- -Represents some UI which can be parented to an ancestor, usually via [Children](./children.md). -The most simple kind of child is a single instance, though arrays can be used -to parent multiple instances at once and state objects can be used to make the -children dynamic. - -```Lua -Instance | {[any]: Child} | StateObject- - Children - - special key - since v0.1 - -
- -Allows parenting children to an instance, both statically and dynamically. - ------ - -## Example Usage - -```Lua -local example = New "Folder" { - [Children] = New "StringValue" { - Value = "I'm parented to the Folder!" - } -} -``` - ------ - -## Processing Children - -A 'child' is defined (recursively) as: - -- an instance -- a [state object](../../state/stateobject) containing children -- an array of children - -Since this definition is recursive, arrays and state objects can be nested; that -is, the following code is valid: - -```Lua -local example = New "Folder" { - [Children] = { - { - { - New "StringValue" { - Value = "I'm parented to the Folder!" - } - } - } - } -} -``` - -This behaviour is especially useful when working with components - the following -component can return multiple instances to be parented without disrupting the -code next to it: - -```Lua -local function Component(props) - return { - New "TextLabel" { - LayoutOrder = 1, - Text = "Instance one" - }, - - New "TextLabel" { - LayoutOrder = 2, - Text = "Instance two" - } - } -end - -local parent = New "Frame" { - Children = { - New "UIListLayout" { - SortOrder = "LayoutOrder" - }, - - Component {} - } -} -``` - -When using a state object as a child, `Children` will interpret the stored value -as children and watch for changes. When the value of the state object changes, -it'll unparent the old children and parent the new children. - -!!! note - As with bound properties, updates are deferred to the next render step, and - so parenting won't occur right away. - -```Lua -local child1 = New "Folder" { - Name = "Child one" -} -local child2 = New "Folder" { - Name = "Child two" -} - -local childState = Value(child1) - -local parent = New "Folder" { - [Children] = childState -} - -print(parent:GetChildren()) -- { Child one } - -childState:set(child2) -wait(1) -- wait for deferred updates to run - -print(parent:GetChildren()) -- { Child two } -``` - -!!! warning - When using state objects, note that old children *won't* be destroyed, only - unparented - it's up to you to decide if/when children need to be destroyed. - ------ - -## Technical Details - -This special key runs at the `descendants` stage. - -On cleanup, all children are unparented, as if wrapped in a state object that -has changed to nil. \ No newline at end of file diff --git a/docs/api-reference/instances/cleanup.md b/docs/api-reference/instances/cleanup.md deleted file mode 100644 index bb9182d96..000000000 --- a/docs/api-reference/instances/cleanup.md +++ /dev/null @@ -1,50 +0,0 @@ - - -- - Cleanup - - special key - since v0.2 - -
- -Cleans up all items given to it when the instance is destroyed, equivalent to -passing the items to `Fusion.cleanup`. - ------ - -## Example Usage - -```Lua -local example1 = New "Folder" { - [Cleanup] = function() - print("I'm in danger!") - end -} - -local example2 = New "Folder" { - [Cleanup] = example1 -} - -local example3 = New "Folder" { - [Cleanup] = { - RunService.RenderStepped:Connect(print), - function() - print("I'm in danger also!") - end, - example2 - } -} - -example3:Destroy() -``` - ------ - -## Technical Details - -This special key runs at the `observer` stage. \ No newline at end of file diff --git a/docs/api-reference/instances/component.md b/docs/api-reference/instances/component.md deleted file mode 100644 index d657c640d..000000000 --- a/docs/api-reference/instances/component.md +++ /dev/null @@ -1,36 +0,0 @@ - - -- - Component - - type - since v0.2 - -
- -The standard type signature for UI components. They accept a property table and -return a [child type](./child.md). - -```Lua -(props: {[any]: any}) -> Child -``` - ------ - -## Example Usage - -```Lua --- create a Button component -local function Button(props) - return New "TextButton" { - Text = props.Text - } -end - --- the Button component is compatible with the Component type -local myComponent: Component = Button -``` \ No newline at end of file diff --git a/docs/api-reference/instances/hydrate.md b/docs/api-reference/instances/hydrate.md deleted file mode 100644 index 21847db32..000000000 --- a/docs/api-reference/instances/hydrate.md +++ /dev/null @@ -1,98 +0,0 @@ - - -- - Hydrate - - function - since v0.2 - -
- -Given an instance, returns a [component](./component.md) which modifies that -instance. The property table may specify properties to set on the instance, or -include [special keys](./specialkey.md) for more advanced operations. - -```Lua -(target: Instance) -> Component -``` - ------ - -## Parameters - -- `target` - the instance which the component should modify - ------ - -## Returns - -A component function. When called, it populates the target instance using the -property table, then returns the target instance. - ------ - -## Example Usage - -```Lua -local myButton: TextButton = Hydrate(PlayerGui.ScreenGui.TextButton) { - Position = UDim2.fromScale(.5, .5), - AnchorPoint = Vector2.new(.5, .5), - Size = UDim2.fromOffset(200, 50), - - Text = "Hello, world!", - - [OnEvent "Activated"] = function() - print("The button was clicked!") - end, - - [OnChange "Name"] = function(newName) - print("The button was renamed to:", newName) - end, - - [Children] = New "UICorner" { - CornerRadius = UDim.new(0, 8) - } -} -``` - ------ - -## Property Table Processing - -The `props` table uses a mix of string and special keys to specify attributes of -the instance which should be set. - -String keys are treated as property declarations - values passed in will be set -upon the instance: - -```Lua -local example = Hydrate(workspace.Part) { - -- sets the Position property - Position = Vector3.new(1, 2, 3) -} -``` - -Passing a state object to a string key will bind the property value; when the -value of the object changes, the property will update to match on the next -resumption step: - -```Lua -local myName = Value("Bob") - -local example = Hydrate(workspace.Part) { - -- initially, the Name will be set to Bob - Name = myName -} - --- change the state object to store "John" --- on the next resumption step, the part's Name will change to John -myName:set("John") -``` - -Special keys, such as [Children](./children.md) or [OnEvent](./onevent.md), may -also be used as keys in the property table. For more information about how -special keys work, [see the SpecialKey page.](./specialkey.md) \ No newline at end of file diff --git a/docs/api-reference/instances/index.md b/docs/api-reference/instances/index.md deleted file mode 100644 index 1546e67eb..000000000 --- a/docs/api-reference/instances/index.md +++ /dev/null @@ -1,110 +0,0 @@ - - -- - Instances -
- -Utilities for connecting state objects to instances via code. - ------ - -
-
-
\ No newline at end of file
diff --git a/docs/api-reference/instances/new.md b/docs/api-reference/instances/new.md
deleted file mode 100644
index d4ae58aed..000000000
--- a/docs/api-reference/instances/new.md
+++ /dev/null
@@ -1,111 +0,0 @@
-
-
-
-### Types
-
-
-
- Child
- :octicons-chevron-right-24:
-
-
-
-
- Component
- :octicons-chevron-right-24:
-
-
-
-
- SpecialKey
- :octicons-chevron-right-24:
-
-
-
-
-### Functions
-
-
- Attribute
- :octicons-chevron-right-24:
-
-
-
-
- AttributeChange
- :octicons-chevron-right-24:
-
-
-
-
- AttributeOut
- :octicons-chevron-right-24:
-
-
-
-
- Hydrate
- :octicons-chevron-right-24:
-
-
-
-
- New
- :octicons-chevron-right-24:
-
-
-
-
- OnChange
- :octicons-chevron-right-24:
-
-
-
-
- OnEvent
- :octicons-chevron-right-24:
-
-
-
-
- Out
- :octicons-chevron-right-24:
-
-
-
-
-### Special Keys
-
-
-
- Children
- :octicons-chevron-right-24:
-
-
-
-
- Cleanup
- :octicons-chevron-right-24:
-
-
-
-
- Ref
- :octicons-chevron-right-24:
-
-
-- - New - - function - since v0.1 - -
- -Given a class name, returns a [component](./component.md) which creates -instances of that class. The property table may specify properties to set on the -instance, or include [special keys](./specialkey.md) for more advanced -operations. - -```Lua -(className: string) -> Component -``` - ------ - -## Parameters - -- `className` - the instance class that should be created - ------ - -## Returns - -A component function. When called, it creates a new instance of the given class, -populates it using the property table, and returns it. - ------ - -## Example Usage - -```Lua -local myButton: TextButton = New "TextButton" { - Parent = Players.LocalPlayer.PlayerGui, - - Position = UDim2.fromScale(.5, .5), - AnchorPoint = Vector2.new(.5, .5), - Size = UDim2.fromOffset(200, 50), - - Text = "Hello, world!", - - [OnEvent "Activated"] = function() - print("The button was clicked!") - end, - - [OnChange "Name"] = function(newName) - print("The button was renamed to:", newName) - end, - - [Children] = New "UICorner" { - CornerRadius = UDim.new(0, 8) - } -} -``` - ------ - -## Property Table Processing - -The `props` table uses a mix of string and special keys to specify attributes of -the instance which should be set. - -String keys are treated as property declarations - values passed in will be set -upon the instance: - -```Lua -local example = New "Part" { - -- sets the Position property - Position = Vector3.new(1, 2, 3) -} -``` - -Passing a state object to a string key will bind the property value; when the -value of the object changes, the property will update to match on the next -resumption step: - -```Lua -local myName = State("Bob") - -local example = New "Part" { - -- initially, the Name will be set to Bob - Name = myName -} - --- change the state object to store "John" --- on the next resumption step, the part's Name will change to John -myName:set("John") -``` - -Special keys, such as [Children](./children.md) or [OnEvent](./onevent.md), may -also be used as keys in the property table. For more information about how -special keys work, [see the SpecialKey page.](./specialkey.md) - ------ - -## Default Properties - -The `New` function provides its own set of 'sensible default' property values -for some class types, which will be used in place of Roblox defaults. This is -done to opt out of some legacy features and unhelpful defaults. - -[You can see the default properties Fusion uses here.](https://github.com/Elttob/Fusion/blob/main/src/Instances/defaultProps.lua) \ No newline at end of file diff --git a/docs/api-reference/instances/onchange.md b/docs/api-reference/instances/onchange.md deleted file mode 100644 index 6abc86a92..000000000 --- a/docs/api-reference/instances/onchange.md +++ /dev/null @@ -1,47 +0,0 @@ - - -- - OnChange - - function - since v0.1 - -
- -Given a property name, returns a [special key](./specialkey.md) which connects -to that property's change events. It should be used with a handler callback, -which may accept the new value of the property. - -```Lua -(propertyName: string) -> SpecialKey -``` - ------ - -## Parameters - -- `propertyName` - The name of the property to listen for changes to. - ------ - -## Returns - -A special key which runs at the `observer` stage. When applied to an instance, -it connects to the property change signal on the instance for the given property. -The handler is run with the property's value after every change. - ------ - -## Example Usage - -```Lua -New "TextBox" { - [OnChange "Text"] = function(newText) - print("You typed:", newText) - end -} -``` \ No newline at end of file diff --git a/docs/api-reference/instances/onevent.md b/docs/api-reference/instances/onevent.md deleted file mode 100644 index d7fb98d7c..000000000 --- a/docs/api-reference/instances/onevent.md +++ /dev/null @@ -1,47 +0,0 @@ - - -- - OnEvent - - function - since v0.1 - -
- -Given an event name, returns a [special key](./specialkey.md) which connects to -events of that name. It should be used with a handler callback, which may accept -arguments from the event. - -```Lua -(eventName: string) -> SpecialKey -``` - ------ - -## Parameters - -- `eventName` - the name of the event to connect to - ------ - -## Returns - -A special key which runs at the `observer` stage. When applied to an instance, -it connects to the event on the instance of the given name. The handler is run -with the event's arguments after every firing. - ------ - -## Example Usage - -```Lua -New "TextButton" { - [OnEvent "Activated"] = function(...) - print("The button was clicked! Arguments:", ...) - end -} -``` \ No newline at end of file diff --git a/docs/api-reference/instances/out.md b/docs/api-reference/instances/out.md deleted file mode 100644 index ae96c955c..000000000 --- a/docs/api-reference/instances/out.md +++ /dev/null @@ -1,50 +0,0 @@ - - -- - Out - - function - since v0.2 - -
- -Given a property name, returns a [special key](./specialkey.md) which outputs -the value of properties with that name. It should be used with a [value](../state/value.md). - -```Lua -(propertyName: string) -> SpecialKey -``` - ------ - -## Parameters - -- `propertyName` - The name of the property to output the value of. - ------ - -## Returns - -A special key which runs at the `observer` stage. When applied to an instance, -it sets the value object equal to the property with the given name. It then -listens for further changes and updates the value object accordingly. - ------ - -## Example Usage - -```Lua -local userText = Value() - -New "TextBox" { - [Out "Text"] = userText -} - -Observer(userText):onChange(function() - print("The user typed:", peek(userText)) -end) -``` \ No newline at end of file diff --git a/docs/api-reference/instances/ref.md b/docs/api-reference/instances/ref.md deleted file mode 100644 index c5d951a79..000000000 --- a/docs/api-reference/instances/ref.md +++ /dev/null @@ -1,39 +0,0 @@ - - -- - Ref - - special key - since v0.2 - -
- -When applied to an instance, outputs the instance to a state object. It should -be used with a [value](../state/value.md). - ------ - -## Example Usage - -```Lua -local myRef = Value() - -New "Part" { - [Ref] = myRef -} - -print(peek(ref)) --> Part -``` - ------ - -## Technical Details - -This special key runs at the `observer` stage. - -On cleanup, the state object is reset to nil, in order to avoid potential -memory leaks. diff --git a/docs/api-reference/instances/specialkey.md b/docs/api-reference/instances/specialkey.md deleted file mode 100644 index 452d58238..000000000 --- a/docs/api-reference/instances/specialkey.md +++ /dev/null @@ -1,110 +0,0 @@ - - -- - SpecialKey - - type - since v0.2 - -
- -The standard interface for special keys that can be used in property tables for -instance processing. Compatible with the [New](./new.md) and -[Hydrate](./hydrate.md) functions. - -```Lua -{ - type: "SpecialKey", - kind: string, - stage: "self" | "descendants" | "ancestor" | "observer", - apply: ( - self: SpecialKey, - value: any, - applyTo: Instance, - cleanupTasks: {Task} - ) -> () -} -``` - ------ - -## Fields - -- `type` - identifies this table as a special key -- `kind` - gives a developer-friendly name to the object for debugging -- `stage` - determines when -the special key should apply itself during the hydration process -- `apply` - the method that will be called to apply the special key to an -instance - ------ - -## Example Usage - -```Lua -local Example = {} -Example.type = "SpecialKey" -Example.kind = "Example" -Example.stage = "observer" - -function Example:apply(value, applyTo, cleanupTasks) - local conn = applyTo:GetAttributeChangedSignal("Foo"):Connect(function() - print("My value is", value) - end) - table.insert(cleanupTasks, conn) -end -``` - ------ - -## Stages - -When using [New](../instances/new.md) and [Hydrate](../instances/hydrate.md), -properties are applied in the following order: - -1. String keys, except Parent -2. Special keys with `stage = "self"` -3. Special keys with `stage = "descendants"` -4. Parent, if provided -5. Special keys with `stage = "ancestor"` -6. Special keys with `stage = "observer"` - -There are multiple motivations for splitting special keys into stages like these: - -- Before we parent descendants to the instance, we want to initialise all of -the instance's properties that don't depend on anything else -- Before we parent the instance to an ancestor, we want to parent and initialise -all of the instance's descendants as fully as possible -- Before we attach handlers to anything, we want to parent to and initialise -the instance's ancestor as fully as possible - -For these reasons, the roles of each stage are as follows: - -### self - -The `self` stage is used for special keys that run before descendants are -parented. This is typically used for special keys that operate on the instance -itself in a vacuum. - -### descendants - -The `descendants` stage is used for special keys that need to deal with -descendants, but which don't need to know about the ancestry. This is important -because parenting descendants after the instance is parented to an ancestor can -be more expensive in terms of performance. - -### ancestor - -The `ancestor` stage is used for special keys that deal with the ancestor of -the instance. This is the last stage that should be used for initialising the -instance, and occurs after the Parent has been set. - -### observer - -The `observer` stage is used for special keys that watch the instance for -changes or export references to the instance. This stage is where any event -handlers should be connected, as initialisation should be done by this point. \ No newline at end of file diff --git a/docs/api-reference/memory/members/derivescope.md b/docs/api-reference/memory/members/derivescope.md new file mode 100644 index 000000000..3fd25b52b --- /dev/null +++ b/docs/api-reference/memory/members/derivescope.md @@ -0,0 +1,60 @@ + + ++ + deriveScope + + -> Scope<T> + +
+ +```Lua +function Fusion.deriveScope+ existing + + : Scope<T> + +
+ +An existing scope, whose methods should be re-used for the new scope. + +----- + ++ Returns + + -> Scope<T> + +
+ +A blank scope with the same methods as the existing scope. + +----- + +## Learn More + +- [Scopes tutorial](../../../../tutorials/fundamentals/scopes) \ No newline at end of file diff --git a/docs/api-reference/memory/members/docleanup.md b/docs/api-reference/memory/members/docleanup.md new file mode 100644 index 000000000..25eb41c40 --- /dev/null +++ b/docs/api-reference/memory/members/docleanup.md @@ -0,0 +1,58 @@ + + ++ + doCleanup + + -> () + +
+ +```Lua +function Fusion.doCleanup( + ...: unknown +): () +``` + +Attempts to destroy all arguments based on their runtime type. + +!!! warning "This is a black hole!" + Any values you pass into `doCleanup` should be treated as completely gone. + Make sure you remove all references to those values, and ensure your code + never uses them again. + +----- + +## Parameters + ++ ... + + : unknown + +
+ +A value which should be disposed of; the value's runtime type will be inspected +to determine what should happen. + +- if `function`, it is called +- ...else if `{destroy: (self) -> ()}`, `:destroy()` is called +- ...else if `{Destroy: (self) -> ()}`, `:Destroy()` is called +- ...else if `{any}`, `doCleanup` is called on all members + +When Fusion is running inside of Roblox: + +- if `Instance`, `:Destroy()` is called +- ...else if `RBXScriptConnection`, `:Disconnect()` is called + +If none of these conditions match, the value is ignored. + +----- + +## Learn More + +- [Scopes tutorial](../../../../tutorials/fundamentals/scopes) \ No newline at end of file diff --git a/docs/api-reference/memory/members/scoped.md b/docs/api-reference/memory/members/scoped.md new file mode 100644 index 000000000..9d8aaf987 --- /dev/null +++ b/docs/api-reference/memory/members/scoped.md @@ -0,0 +1,61 @@ + + ++ + scoped + + -> Scope<T> + +
+ +```Lua +function Fusion.scoped+ constructors + + : T + +
+ +A table, ideally including functions which take a scope as their first +parameter. Those functions will turn into methods. + +----- + ++ Returns + + -> Scope<T> + +
+ +A blank scope with the specified methods. + +----- + +## Learn More + +- [Scopes tutorial](../../../../tutorials/fundamentals/scopes) \ No newline at end of file diff --git a/docs/api-reference/memory/types/scope.md b/docs/api-reference/memory/types/scope.md new file mode 100644 index 000000000..3cf13a4ae --- /dev/null +++ b/docs/api-reference/memory/types/scope.md @@ -0,0 +1,31 @@ + + ++ + Scope +
+ +```Lua +export type Scope+ + ScopedObject +
+ +```Lua +export type ScopedObject = { + scope: Scope+ scope + + : Scope<unknown>? + +
+ +The scope which this object was constructed with, or `nil` if the object has +been destroyed. + +!!! note "Unchanged until destruction" + The `scope` is expected to be set once upon construction. It should not be + assigned to again, except when the scope is destroyed - at which point it + should be set to `nil` to indicate that it no longer exists inside of a + scope. This is typically done inside the `:destroy()` method, if it exists. + +----- + +## Methods + ++ destroy + + -> () + +
+ +```Lua +function ScopedObject:destroy(): () +``` + +Called by `doCleanup` to destroy this object. User code should generally not +call this; instead, destroy the scope as a whole. + +!!! tip "Double-destruction prevention" + Fusion's objects throw + [`destroyedTwice`](../../../general/errors/#destroyedtwice) if they detect + a `nil` scope during`:destroy()`. + + It's strongly recommended that you emulate this behaviour if you're + implementing your own objects, as this protects against double-destruction + and exposes potential scoping issues further ahead of time. + +----- + +## Learn More + +- [Scopes tutorial](../../../../tutorials/fundamentals/scopes) \ No newline at end of file diff --git a/docs/api-reference/memory/types/task.md b/docs/api-reference/memory/types/task.md new file mode 100644 index 000000000..3e34c1785 --- /dev/null +++ b/docs/api-reference/memory/types/task.md @@ -0,0 +1,33 @@ + + ++ + Task +
+ +```Lua +export type Task = + Instance + | RBXScriptConnection + | () -> () + | {destroy: (self) -> ()} + | {Destroy: (self) -> ()} + | {Task} +``` +Types which [`doCleanup`](../../members/docleanup) has defined behaviour for. + +!!! warning "Not enforced" + Fusion does not use static types to enforce that `doCleanup` is given a type + which it can process. + + This type is only exposed for your own use. + +----- + +## Learn More + +- [Scopes tutorial](../../../../tutorials/fundamentals/scopes) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/attribute.md b/docs/api-reference/roblox/members/attribute.md new file mode 100644 index 000000000..f05d5eee7 --- /dev/null +++ b/docs/api-reference/roblox/members/attribute.md @@ -0,0 +1,49 @@ + + ++ + Attribute + + -> SpecialKey + +
+ +```Lua +function Fusion.Attribute( + attributeName: string +): SpecialKey +``` + +Given an attribute name, returns a [special key](../../types/specialkey) which +can modify attributes of that name. + +When paired with a value in a [property table](../../types/propertytable), the +special key sets the attribute to that value. + +----- + +## Parameters + ++ attributeName + + : string + +
+ +The name of the attribute that the special key should target. + +----- + ++ Returns + + -> SpecialKey + +
+ +A special key for modifying attributes of that name. \ No newline at end of file diff --git a/docs/api-reference/roblox/members/attributechange.md b/docs/api-reference/roblox/members/attributechange.md new file mode 100644 index 000000000..7b0994833 --- /dev/null +++ b/docs/api-reference/roblox/members/attributechange.md @@ -0,0 +1,49 @@ + + ++ + AttributeChange + + -> SpecialKey + +
+ +```Lua +function Fusion.AttributeChange( + attributeName: string +): SpecialKey +``` + +Given an attribute name, returns a [special key](../../types/specialkey) which +can listen to changes for attributes of that name. + +When paired with a callback in a [property table](../../types/propertytable), +the special key connects the callback to the attribute's change event. + +----- + +## Parameters + ++ attributeName + + : string + +
+ +The name of the attribute that the special key should target. + +----- + ++ Returns + + -> SpecialKey + +
+ +A special key for listening to changes for attributes of that name. \ No newline at end of file diff --git a/docs/api-reference/roblox/members/attributeout.md b/docs/api-reference/roblox/members/attributeout.md new file mode 100644 index 000000000..8ec480811 --- /dev/null +++ b/docs/api-reference/roblox/members/attributeout.md @@ -0,0 +1,50 @@ + + ++ + AttributeOut + + -> SpecialKey + +
+ +```Lua +function Fusion.AttributeOut( + attributeName: string +): SpecialKey +``` + +Given an attribute name, returns a [special key](../../types/specialkey) which +can output values from attributes of that name. + +When paired with a [value object](../../../state/types/value) in a +[property table](../../types/propertytable), the special key sets the value when +the attribute changes. + +----- + +## Parameters + ++ attributeName + + : string + +
+ +The name of the attribute that the special key should target. + +----- + ++ Returns + + -> SpecialKey + +
+ +A special key for outputting values from attributes of that name. \ No newline at end of file diff --git a/docs/api-reference/roblox/members/children.md b/docs/api-reference/roblox/members/children.md new file mode 100644 index 000000000..859e77286 --- /dev/null +++ b/docs/api-reference/roblox/members/children.md @@ -0,0 +1,34 @@ + + ++ + Children + + : SpecialKey + +
+ +```Lua +Fusion.Children: SpecialKey +``` + +A [special key](../../types/specialkey) which parents other instances into this +instance. + +When paired with a [`Child`](../../types/child) in a +[property table](../../types/propertytable), the special key explores the +`Child` to find every `Instance` nested inside. It then parents those instances +under the instance which the special key was applied to. + +In particular, this special key will recursively explore arrays and bind to any +[state objects](../../../state/types/stateobject). + +----- + +## Learn More + +- [Parenting tutorial](../../../../tutorials/roblox/parenting) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/hydrate.md b/docs/api-reference/roblox/members/hydrate.md new file mode 100644 index 000000000..6a1ee75de --- /dev/null +++ b/docs/api-reference/roblox/members/hydrate.md @@ -0,0 +1,72 @@ + + ++ + Hydrate + + -> (PropertyTable) -> Instance + +
+ +```Lua +function Fusion.Hydrate( + target: Instance +): ( + props: PropertyTable +) -> Instance +``` + +Given an instance, returns a component for binding extra functionality to that +instance. + +In the property table, string keys are assigned as properties on the instance. +If the value is a [state object](../../../state/types/stateobject), it is +re-assigned every time the value of the state object changes. + +Any [special keys](../../types/specialkey) present in the property table are +applied to the instance after string keys are processed, in the order specified +by their `stage`. + +A special exception is made for assigning `Parent`, which is only assigned after +the `descendants` stage. + +!!! warning "Do not overwrite properties" + If the instance was previously created with [`New`](../new) or previously + hydrated, do not assign to any properties that were previously specified in + those prior calls. Duplicated assignments can interfere with each other in + unpredictable ways. + +----- + +## Parameters + ++ target + + : Instance + +
+ +The instance which should be modified. + +----- + ++ Returns + + -> (PropertyTable) -> Instance + +
+ +A component that hydrates that instance, accepting various properties to build +up bindings and operations applied to the instance. + +----- + +## Learn More + +- [Hydration tutorial](../../../../tutorials/roblox/hydration) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/new.md b/docs/api-reference/roblox/members/new.md new file mode 100644 index 000000000..5b9bf85c8 --- /dev/null +++ b/docs/api-reference/roblox/members/new.md @@ -0,0 +1,66 @@ + + ++ + New + + -> (PropertyTable) -> Instance + +
+ +```Lua +function Fusion.New( + className: string +): ( + props: PropertyTable +) -> Instance +``` + +Given a class name, returns a component for constructing instances of that +class. + +In the property table, string keys are assigned as properties on the instance. +If the value is a [state object](../../../state/types/stateobject), it is +re-assigned every time the value of the state object changes. + +Any [special keys](../../types/specialkey) present in the property table are +applied to the instance after string keys are processed, in the order specified +by their `stage`. + +A special exception is made for assigning `Parent`, which is only assigned after +the `descendants` stage. + +----- + +## Parameters + ++ className + + : string + +
+ +The kind of instance that should be constructed. + +----- + ++ Returns + + -> (PropertyTable) -> Instance + +
+ +A component that constructs instances of that type, accepting various properties +to customise each instance uniquely. + +----- + +## Learn More + +- [New Instances tutorial](../../../../tutorials/roblox/new-instances) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/onchange.md b/docs/api-reference/roblox/members/onchange.md new file mode 100644 index 000000000..341d4a854 --- /dev/null +++ b/docs/api-reference/roblox/members/onchange.md @@ -0,0 +1,55 @@ + + ++ + OnChange + + -> SpecialKey + +
+ +```Lua +function Fusion.OnChange( + propertyName: string +): SpecialKey +``` + +Given an property name, returns a [special key](../../types/specialkey) which +can listen to changes for properties of that name. + +When paired with a callback in a [property table](../../types/propertytable), +the special key connects the callback to the property's change event. + +----- + +## Parameters + ++ propertyName + + : string + +
+ +The name of the property that the special key should target. + +----- + ++ Returns + + -> SpecialKey + +
+ +A special key for listening to changes for properties of that name. + +----- + +## Learn More + +- [Change Events tutorial](../../../../tutorials/roblox/change-events) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/onevent.md b/docs/api-reference/roblox/members/onevent.md new file mode 100644 index 000000000..1ed718768 --- /dev/null +++ b/docs/api-reference/roblox/members/onevent.md @@ -0,0 +1,55 @@ + + ++ + OnEvent + + -> SpecialKey + +
+ +```Lua +function Fusion.OnEvent( + eventName: string +): SpecialKey +``` + +Given an event name, returns a [special key](../../types/specialkey) which +can listen for events of that name. + +When paired with a callback in a [property table](../../types/propertytable), +the special key connects the callback to the event. + +----- + +## Parameters + ++ eventName + + : string + +
+ +The name of the event that the special key should target. + +----- + ++ Returns + + -> SpecialKey + +
+ +A special key for listening to events of that name. + +----- + +## Learn More + +- [Events tutorial](../../../../tutorials/roblox/events) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/out.md b/docs/api-reference/roblox/members/out.md new file mode 100644 index 000000000..9dfa5c9e9 --- /dev/null +++ b/docs/api-reference/roblox/members/out.md @@ -0,0 +1,56 @@ + + ++ + Out + + -> SpecialKey + +
+ +```Lua +function Fusion.Out( + propertyName: string +): SpecialKey +``` + +Given an property name, returns a [special key](../../types/specialkey) which +can output values from properties of that name. + +When paired with a [value object](../../../state/types/value) in a +[property table](../../types/propertytable), the special key sets the value when +the property changes. + +----- + +## Parameters + ++ propertyName + + : string + +
+ +The name of the property that the special key should target. + +----- + ++ Returns + + -> SpecialKey + +
+ +A special key for outputting values from properties of that name. + +----- + +## Learn More + +- [Outputs tutorial](../../../../tutorials/roblox/outputs) \ No newline at end of file diff --git a/docs/api-reference/roblox/members/ref.md b/docs/api-reference/roblox/members/ref.md new file mode 100644 index 000000000..83f9e449e --- /dev/null +++ b/docs/api-reference/roblox/members/ref.md @@ -0,0 +1,30 @@ + + ++ + Ref + + : SpecialKey + +
+ +```Lua +Fusion.Ref: SpecialKey +``` + +A [special key](../../types/specialkey) which outputs the instance it's being +applied to. + +When paired with a [value object](../../../state/types/value) in a +[property table](../../types/propertytable), the special key sets the value to +the instance. + +----- + +## Learn More + +- [References tutorial](../../../../tutorials/roblox/references) \ No newline at end of file diff --git a/docs/api-reference/roblox/types/child.md b/docs/api-reference/roblox/types/child.md new file mode 100644 index 000000000..67d14d21b --- /dev/null +++ b/docs/api-reference/roblox/types/child.md @@ -0,0 +1,24 @@ + + ++ + Child +
+ +```Lua +export type Child = Instance | StateObject+ + PropertyTable +
+ +```Lua +export type PropertyTable = {[string | SpecialKey]: unknown} +``` + +A table of named instance properties and [special keys](../specialkey), which +can be passed to [`New`](../../members/new) to create an instance. + +!!! warning "This type can be overly generic" + In most cases, you should know what properties your code is looking for. In + those cases, you should prefer to list out the properties explicitly, to + document what your code needs. + + You should only use this type if you don't know what properties your code + will accept. diff --git a/docs/api-reference/roblox/types/specialkey.md b/docs/api-reference/roblox/types/specialkey.md new file mode 100644 index 000000000..f6dd3cbe6 --- /dev/null +++ b/docs/api-reference/roblox/types/specialkey.md @@ -0,0 +1,99 @@ + + ++ + SpecialKey +
+ +```Lua +export type SpecialKey = { + type: "SpecialKey", + kind: string, + stage: "self" | "descendants" | "ancestor" | "observer", + apply: ( + self, + scope: Scope+ type + + : "SpecialKey" + +
+ +A type string which can be used for runtime type checking. + + ++ kind + + : string + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of special key apart. + ++ stage + + : "self" | "descendants" | "ancestor" | "observer" + +
+ +Describes the type of operation, which subsequently determines when it's applied +relative to other operations. + +- `self` runs before parenting any instances +- `descendants` runs once descendants are parented, but before this instance is +parented to its ancestor +- `ancestor` runs after all parenting operations are complete +- `observer` runs after all other operations, so the final state of the instance +can be observed + +----- + +## Methods + ++ apply + + -> () + +
+ +```Lua +function SpecialKey:apply( + self, + scope: Scope- - CanBeState - - type - since v0.2 - -
- -A value which may either be a [state object](../stateobject) or a constant. - -Provided as a convenient shorthand for indicating that constant-ness is not -important. - -```Lua -StateObject- - cleanup - - function - since v0.2 - -
- -Attempts to destroy all destructible objects passed to it. - -```Lua -(...any) -> () -``` - ------ - -## Parameters - -- `...` - Any objects that need to be destroyed. - ------ - -## Example Usage - -```Lua -Fusion.cleanup( - workspace.Part1, - RunService.RenderStepped:Connect(print), - function() - print("I will be run!") - end -) -``` - ------ - -## Destruction Behaviour - -Destruction behaviour varies by type: - -- if `Instance`, `:Destroy()` is called -- ...else if `RBXScriptConnection`, `:Disconnect()` is called -- ...else if `function`, it is called -- ...else if `{destroy: (self) -> ()}`, `:destroy()` is called -- ...else if `{Destroy: (self) -> ()}`, `:Destroy()` is called -- ...else if `{any}`, `Fusion.cleanup` is called on all members -- ...else nothing occurs. \ No newline at end of file diff --git a/docs/api-reference/state/computed.md b/docs/api-reference/state/computed.md deleted file mode 100644 index 57bda66dc..000000000 --- a/docs/api-reference/state/computed.md +++ /dev/null @@ -1,78 +0,0 @@ - - -- - Computed - - state object - since v0.1 - -
- -Calculates a single value based on the returned values from other state objects. - -```Lua -( - processor: (Use) -> (T, M), - destructor: ((T, M) -> ())? -) -> Computed- - Dependency - - type - since v0.2 - -
- -A graph object which can send updates to [dependents](../dependent) on the -reactive graph. - -Most often used with [state objects](../stateobject), though the reactive graph -does not require objects to store state. - -```Lua -{ - dependentSet: Set- - Dependent - - type - since v0.2 - -
- -A graph object which can receive updates from [dependecies](../dependency) on -the reactive graph. - -Most often used with [state objects](../stateobject), though the reactive graph -does not require objects to store state. - -```Lua -{ - dependencySet: Set- since v0.2 -
- -### :octicons-code-24: Dependent:update() - -Called when this object receives an update from one or more dependencies. - -If this object is a dependency, and updates should be propagated to further -dependencies, this method should return true. Otherwise, to block further -updates from occuring (for example, because this object did not change value), -this method should return false. - -```Lua -() -> boolean -``` - ------ - -## Example Usage - -```Lua --- these are examples of objects which are dependents -local computed: Dependent = Computed(function(use) - return "foo" -end) -local observer: Dependent = Observer(computed) -``` \ No newline at end of file diff --git a/docs/api-reference/state/donothing.md b/docs/api-reference/state/donothing.md deleted file mode 100644 index 0c11a522f..000000000 --- a/docs/api-reference/state/donothing.md +++ /dev/null @@ -1,36 +0,0 @@ - - -- - doNothing - - function - since v0.2 - -
- -No-op function - does nothing at all, and returns nothing at all. Intended for -use as a destructor when no destruction is needed. - -```Lua -(...any) -> () -``` - ------ - -## Parameters - -- `...` - Any objects. - ------ - -## Example Usage - -```Lua -local foo = Computed(function(use) - return workspace.Part -end, Fusion.doNothing) -``` \ No newline at end of file diff --git a/docs/api-reference/state/forkeys.md b/docs/api-reference/state/forkeys.md deleted file mode 100644 index 69992c7ed..000000000 --- a/docs/api-reference/state/forkeys.md +++ /dev/null @@ -1,93 +0,0 @@ - - -- - ForKeys - - state object - since v0.2 - -
- -Processes a table from another state object by transforming its keys only. - -```Lua -( - input: CanBeState<{[KI]: V}>, - keyProcessor: (Use, KI) -> (KO, M), - keyDestructor: ((KO, M) -> ())? -) -> ForKeys- - ForPairs - - state object - since v0.2 - -
- -Processes a table from another state object by transforming its keys and values. - -```Lua -( - input: CanBeState<{[KI]: VI}>, - pairProcessor: (Use, KI, VI) -> (KO, VO, M), - pairDestructor: ((KO, VO, M) -> ())? -) -> ForPairs- - ForValues - - state object - since v0.2 - -
- -Processes a table from another state object by transforming its values only. - -```Lua -( - input: CanBeState<{[K]: VI}>, - valueProcessor: (Use, VI) -> (VO, M), - valueDestructor: ((VO, M) -> ())? -) -> ForValues- - State -
- -Fundamental state objects and utilities for working with reactive graphs. - ------ - -
-
-
\ No newline at end of file
diff --git a/docs/api-reference/state/members/computed.md b/docs/api-reference/state/members/computed.md
new file mode 100644
index 000000000..5b4846dd3
--- /dev/null
+++ b/docs/api-reference/state/members/computed.md
@@ -0,0 +1,73 @@
+
+
+
-### Types
-
-
-
- CanBeState
- :octicons-chevron-right-24:
-
-
-
-
- Dependency
- :octicons-chevron-right-24:
-
-
-
-
- Dependent
- :octicons-chevron-right-24:
-
-
-
-
- StateObject
- :octicons-chevron-right-24:
-
-
-
-
- Use
- :octicons-chevron-right-24:
-
-
-
-
-### Functions
-
-
-
- cleanup
- :octicons-chevron-right-24:
-
-
-
-
- doNothing
- :octicons-chevron-right-24:
-
-
-
-
- peek
- :octicons-chevron-right-24:
-
-
-
-
-### State Objects
-
-
-
- Computed
- :octicons-chevron-right-24:
-
-
-
-
- ForKeys
- :octicons-chevron-right-24:
-
-
-
-
- ForPairs
- :octicons-chevron-right-24:
-
-
-
-
- ForValues
- :octicons-chevron-right-24:
-
-
-
-
- Observer
- :octicons-chevron-right-24:
-
-
-
-
- Value
- :octicons-chevron-right-24:
-
-
-
-+ + Computed + + -> Computed<T> + +
+ +```Lua +function Fusion.Computed+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ processor + + : (Use, + Scope<S>) -> T + +
+ +Computes the value that will be used by the computed. The processor is given a +[use function](../../../memory/types/use) for including other objects in the +computation, and a [scope](../../../memory/types/scope) for queueing destruction +tasks to run on re-computation. The given scope has the same methods as the +scope used to create the computed. + +----- + ++ Returns + + -> Computed<T> + +
+ +A freshly constructed computed state object. + +----- + +## Learn More + +- [Computeds tutorial](../../../../tutorials/fundamentals/computeds) \ No newline at end of file diff --git a/docs/api-reference/state/members/forkeys.md b/docs/api-reference/state/members/forkeys.md new file mode 100644 index 000000000..f67ff5231 --- /dev/null +++ b/docs/api-reference/state/members/forkeys.md @@ -0,0 +1,89 @@ + + ++ + ForKeys + + -> For<KO, V> + +
+ +```Lua +function Fusion.ForKeys+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ inputTable + + : CanBeState<{[KI]: V}> + +
+ +The table which will provide the input keys and input values for this object. + +If it is a state object, this object will respond to changes in that state. + ++ processor + + : (Use, + Scope<S>, + key: KI) -> KO + +
+ +Accepts a `KI` key from the input table, and returns the `KO` key that should +appear in the output table. + +The processor is given a [use function](../../../memory/types/use) for including +other objects in the computation, and a [scope](../../../memory/types/scope) for +queueing destruction tasks to run on re-computation. The given scope has the +same methods as the scope used to create the whole object. + +----- + ++ Returns + + -> For<KO, V> + +
+ +A freshly constructed For state object. + +----- + +## Learn More + +- [ForKeys tutorial](../../../../tutorials/tables/forkeys) \ No newline at end of file diff --git a/docs/api-reference/state/members/forpairs.md b/docs/api-reference/state/members/forpairs.md new file mode 100644 index 000000000..4ea1f7034 --- /dev/null +++ b/docs/api-reference/state/members/forpairs.md @@ -0,0 +1,89 @@ + + ++ + ForPairs + + -> For<KO, VO> + +
+ +```Lua +function Fusion.ForPairs+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ inputTable + + : CanBeState<{[KI]: VI}> + +
+ +The table which will provide the input keys and input values for this object. + +If it is a state object, this object will respond to changes in that state. + ++ processor + + : (Use, + Scope<S>, + key: KI, value: VI) -> (KO, VO) + +
+ +Accepts a `KI` key and `VI` value pair from the input table, and returns the +`KO` key and `VO` value pair that should appear in the output table. + +The processor is given a [use function](../../../memory/types/use) for including +other objects in the computation, and a [scope](../../../memory/types/scope) for +queueing destruction tasks to run on re-computation. The given scope has the +same methods as the scope used to create the whole object. + +----- + ++ Returns + + -> For<KO, VO> + +
+ +A freshly constructed For state object. + +----- + +## Learn More + +- [ForPairs tutorial](../../../../tutorials/tables/forpairs) \ No newline at end of file diff --git a/docs/api-reference/state/members/forvalues.md b/docs/api-reference/state/members/forvalues.md new file mode 100644 index 000000000..746b405da --- /dev/null +++ b/docs/api-reference/state/members/forvalues.md @@ -0,0 +1,89 @@ + + ++ + ForValues + + -> For<K, VO> + +
+ +```Lua +function Fusion.ForValues+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ inputTable + + : CanBeState<{[K]: VI}> + +
+ +The table which will provide the input keys and input values for this object. + +If it is a state object, this object will respond to changes in that state. + ++ processor + + : (Use, + Scope<S>, + value: VI) -> VO + +
+ +Accepts a `VI` value from the input table, and returns the `VO` value that +should appear in the output table. + +The processor is given a [use function](../../../memory/types/use) for including +other objects in the computation, and a [scope](../../../memory/types/scope) for +queueing destruction tasks to run on re-computation. The given scope has the +same methods as the scope used to create the whole object. + +----- + ++ Returns + + -> For<K, VO> + +
+ +A freshly constructed For state object. + +----- + +## Learn More + +- [ForValues tutorial](../../../../tutorials/tables/forvalues) \ No newline at end of file diff --git a/docs/api-reference/state/members/observer.md b/docs/api-reference/state/members/observer.md new file mode 100644 index 000000000..6323d1c71 --- /dev/null +++ b/docs/api-reference/state/members/observer.md @@ -0,0 +1,68 @@ + + ++ + Observer + + -> Observer + +
+ +```Lua +function Fusion.Observer( + scope: Scope+ scope + + : Scope<unknown> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ watching + + : Dependency + +
+ +The object which the observer should receive updates from. + +----- + ++ Returns + + -> Observer + +
+ +A freshly constructed observer. + +----- + +## Learn More + +- [Observers tutorial](../../../../tutorials/fundamentals/observers) \ No newline at end of file diff --git a/docs/api-reference/state/members/peek.md b/docs/api-reference/state/members/peek.md new file mode 100644 index 000000000..84a793632 --- /dev/null +++ b/docs/api-reference/state/members/peek.md @@ -0,0 +1,69 @@ + + ++ + peek + + : Use + +
+ +```Lua +function Fusion.peek+ target + + : CanBeState<T> + +
+ +The abstract representation of `T` to extract a value from. + +----- + ++ Returns + + -> T + +
+ +The current value of `T`, derived from `target`. + +----- + +## Learn More + +- [Values tutorial](../../../../tutorials/fundamentals/values/) \ No newline at end of file diff --git a/docs/api-reference/state/members/value.md b/docs/api-reference/state/members/value.md new file mode 100644 index 000000000..369b42cee --- /dev/null +++ b/docs/api-reference/state/members/value.md @@ -0,0 +1,68 @@ + + ++ + Value + + -> Value<T> + +
+ +```Lua +function Fusion.Value+ scope + + : Scope<S> + +
+ +The [scope](../../../memory/types/scope) which should be used to store +destruction tasks for this object. + ++ initialValue + + : T + +
+ +The initial value that will be stored until the next value is `:set()`. + +----- + ++ Returns + + -> Value<T> + +
+ +A freshly constructed value state object. + +----- + +## Learn More + +- [Values tutorial](../../../../tutorials/fundamentals/values) \ No newline at end of file diff --git a/docs/api-reference/state/observer.md b/docs/api-reference/state/observer.md deleted file mode 100644 index ab53d4cfc..000000000 --- a/docs/api-reference/state/observer.md +++ /dev/null @@ -1,115 +0,0 @@ - - -- - Observer - - graph object - since v0.2 - -
- -Observes various updates and events on a given dependency. - -```Lua -( - observe: Dependency -) -> Observer -``` - ------ - -## Parameters - -- `observe: Dependency` - the dependency this observer should respond to - ------ - -## Object Methods - -- since v0.2 -
- -### :octicons-code-24: Observer:onChange() - -Connects the given callback as a change handler, and returns a function which -will disconnect the callback. The callback will run whenever the observed -dependency is updated. - -```Lua -(callback: () -> ()) -> (() -> ()) -``` -#### Parameters - -- `callback` - The function to call when a change is observed - -!!! caution "Connection memory leaks" - Make sure to disconnect any change handlers made using this function once - you're done using them. - - As long as a change handler is connected, this observer and the dependency - it observes will be held in memory in case further changes occur. This means, - if you don't call the disconnect function, you may end up accidentally - holding your state objects in memory forever after you're done using them. - ------ - -- since v0.3 -
- -### :octicons-code-24: Observer:onBind() - -Connects the given callback as a change handler, and returns a function which will disconnect the callback. The callback is run immediately, and re-run whenever the observed dependency is updated. - -```Lua -(callback: () -> ()) -> (() -> ()) -``` -#### Parameters - -- `callback` - The function to call when a change is observed **and** when the observer is created - -!!! caution "Connection memory leaks" - Make sure to disconnect any change handlers made using this function once - you're done using them. - - As long as a change handler is connected, this observer and the dependency - it observes will be held in memory in case further changes occur. This means, - if you don't call the disconnect function, you may end up accidentally - holding your state objects in memory forever after you're done using them. - ------ - -## Example Usage - -```Lua -local numCoins = Value(50) - -local coinObserver = Observer(numCoins) - -local disconnect = coinObserver:onChange(function() - print("coins is now:", peek(numCoins)) -end) - -numCoins:set(25) -- prints 'coins is now: 25' - --- always clean up your connections! -disconnect() -``` - -```Lua -local someValue = Value("") - -function update() - someObject.Text = peek(someValue) -end - -local disconnect = Observer(someValue):onBind(update) - --- always clean up your connections! -disconnect() -``` \ No newline at end of file diff --git a/docs/api-reference/state/peek.md b/docs/api-reference/state/peek.md deleted file mode 100644 index cfd14a47a..000000000 --- a/docs/api-reference/state/peek.md +++ /dev/null @@ -1,43 +0,0 @@ - - -- - peek - - function - since v0.3 - -
- -The most basic [use callback](./use.md), which returns the interior value of -state objects without adding any dependencies. - -```Lua -- - StateObject - - type - since v0.2 - -
- -A dependency that provides a single stateful value; the dependency updates when -the value changes state. - -Note that state objects do not expose a public interface for accessing their -interior value - the standard way of doing this is by using a -[use callback](./use.md) such as the [peek function](./peek.md). - -```Lua -Dependency & { - type: "State", - kind: string -} -``` - ------ - -## Fields - -- `type` - uniquely identifies state objects for runtime type checks -- `kind` - holds a more specific type name for different kinds of state object - ------ - -## Example Usage - -```Lua --- these are examples of objects which are state objects -local value: StateObject = Value(5) -local computed: StateObject = Computed(function(use) - return "foo" -end) -``` \ No newline at end of file diff --git a/docs/api-reference/state/types/canbestate.md b/docs/api-reference/state/types/canbestate.md new file mode 100644 index 000000000..826c74278 --- /dev/null +++ b/docs/api-reference/state/types/canbestate.md @@ -0,0 +1,35 @@ + + ++ + CanBeState +
+ +```Lua +export type CanBeState+ + Computed +
+ +```Lua +export type Computed+ kind + + : "Computed" + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of state object apart. + +----- + +## Learn More + +- [Computeds tutorial](../../../../tutorials/fundamentals/computeds) \ No newline at end of file diff --git a/docs/api-reference/state/types/dependency.md b/docs/api-reference/state/types/dependency.md new file mode 100644 index 000000000..fd4d7969a --- /dev/null +++ b/docs/api-reference/state/types/dependency.md @@ -0,0 +1,37 @@ + + ++ + Dependency +
+ +```Lua +export type Dependency = ScopedObject & { + dependentSet: {[Dependent]: unknown} +} +``` + +A reactive graph object which can broadcast updates. Other graph objects can +declare themselves as [dependent](../dependent) upon this object to receive +updates. + +This type includes [`ScopedObject`](../../../memory/types/scopedobject), which +allows the lifetime and destruction order of the reactive graph to be analysed. + +----- + +## Members + ++ dependentSet + + : {[Dependent]: unknown} + +
+ +The reactive graph objects which declare themselves as dependent upon this +object. \ No newline at end of file diff --git a/docs/api-reference/state/types/dependent.md b/docs/api-reference/state/types/dependent.md new file mode 100644 index 000000000..613d1c6b7 --- /dev/null +++ b/docs/api-reference/state/types/dependent.md @@ -0,0 +1,65 @@ + + ++ + Dependent +
+ +```Lua +export type Dependent = ScopedObject & { + update: (self) -> boolean, + dependencySet: {[Dependency]: unknown} +} +``` + +A reactive graph object which can add itself to [dependencies](../dependency) +and receive updates. + +This type includes [`ScopedObject`](../../../memory/types/scopedobject), which +allows the lifetime and destruction order of the reactive graph to be analysed. + +!!! note "Non-standard type syntax" + The above type definition uses `self` to denote methods. At time of writing, + Luau does not interpret `self` specially. + +----- + +## Members + ++ dependencySet + + : {[Dependency]: unknown} + +
+ +Everything this reactive graph object currently declares itself as dependent +upon. + +----- + +## Methods + ++ update + + -> boolean + +
+ +```Lua +function Dependent:update(): boolean +``` + +Called from a dependency when a change occurs. Returns `true` if the update +should propagate transitively through this object, or `false` if the update +should not continue through this object specifically. + +!!! note "Return value ignored for non-dependencies" + If this `Dependent` is not also a `Dependency`, the return value does + nothing, as an object must be declarable as a dependency for other objects + to receive updates from it. diff --git a/docs/api-reference/state/types/for.md b/docs/api-reference/state/types/for.md new file mode 100644 index 000000000..ea85c8b44 --- /dev/null +++ b/docs/api-reference/state/types/for.md @@ -0,0 +1,47 @@ + + ++ + For +
+ +```Lua +export type For+ kind + + : "For" + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of state object apart. + +----- + +## Learn More + +- [ForValues tutorial](../../../../tutorials/tables/forvalues) +- [ForKeys tutorial](../../../../tutorials/tables/forkeys) +- [ForPairs tutorial](../../../../tutorials/tables/forpairs) \ No newline at end of file diff --git a/docs/api-reference/state/types/observer.md b/docs/api-reference/state/types/observer.md new file mode 100644 index 000000000..e133ed33d --- /dev/null +++ b/docs/api-reference/state/types/observer.md @@ -0,0 +1,83 @@ + + ++ + Observer +
+ +```Lua +export type Observer = Dependent & { + type: "Observer", + onChange: (self, callback: () -> ()) -> (() -> ()), + onBind: (self, callback: () -> ()) -> (() -> ()) +} +``` + +A user-constructed [dependent](../dependent) that runs user code when its +[dependency](../dependency) is updated. + +!!! note "Non-standard type syntax" + The above type definition uses `self` to denote methods. At time of writing, + Luau does not interpret `self` specially. + +----- + +## Members + ++ type + + : "Observer" + +
+ +A type string which can be used for runtime type checking. + +----- + +## Methods + ++ onChange + + -> (() -> ()) + +
+ +```Lua +function Observer:onChange( + callback: () -> () +): (() -> ()) +``` + +Registers the callback to run when an update is received. + +The returned function will unregister the callback. + ++ onBind + + -> (() -> ()) + +
+ +```Lua +function Observer:onBind( + callback: () -> () +): (() -> ()) +``` + +Runs the callback immediately, and registers the callback to run when an update +is received. + +The returned function will unregister the callback. + +----- + +## Learn More + +- [Observers tutorial](../../../../tutorials/fundamentals/observers) \ No newline at end of file diff --git a/docs/api-reference/state/types/stateobject.md b/docs/api-reference/state/types/stateobject.md new file mode 100644 index 000000000..bfb90860c --- /dev/null +++ b/docs/api-reference/state/types/stateobject.md @@ -0,0 +1,46 @@ + + ++ + StateObject +
+ +```Lua +export type StateObject+ type + + : "State" + +
+ +A type string which can be used for runtime type checking. + ++ kind + + : string + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of state object apart. \ No newline at end of file diff --git a/docs/api-reference/state/types/use.md b/docs/api-reference/state/types/use.md new file mode 100644 index 000000000..13885608d --- /dev/null +++ b/docs/api-reference/state/types/use.md @@ -0,0 +1,58 @@ + + ++ + Use +
+ +```Lua +export type Use =+ target + + : CanBeState<T> + +
+ +The abstract representation of `T` to extract a value from. + +----- + ++ Returns + + -> T + +
+ +The current value of `T`, derived from `target`. + +----- + +## Learn More + +- [Values tutorial](../../../../tutorials/fundamentals/values/) +- [Computeds tutorial](../../../../tutorials/fundamentals/computeds/) \ No newline at end of file diff --git a/docs/api-reference/state/types/value.md b/docs/api-reference/state/types/value.md new file mode 100644 index 000000000..65cfa665f --- /dev/null +++ b/docs/api-reference/state/types/value.md @@ -0,0 +1,65 @@ + + ++ + Value +
+ +```Lua +export type Value+ kind + + : "Value" + +
+ +A more specific type string which can be used for runtime type checking. This +can be used to tell types of state object apart. + +----- + +## Methods + ++ set + + -> () + +
+ +```Lua +function Value:set( + newValue: T +): () +``` + +Updates the value of this state object. + +Other objects using the value are notified immediately of the change. + +----- + +## Learn More + +- [Values tutorial](../../../../tutorials/fundamentals/values) \ No newline at end of file diff --git a/docs/api-reference/state/use.md b/docs/api-reference/state/use.md deleted file mode 100644 index baf155729..000000000 --- a/docs/api-reference/state/use.md +++ /dev/null @@ -1,35 +0,0 @@ - - -- - Use - - type - since v0.3 - -
- -The general function signature for unwrapping [state objects](./stateobject.md) -while transparently passing through other (constant) values. - -Functions of this shape are often referred to as 'use callbacks', and are often -provided by dependency capturers such as [computeds](./computed.md) for the -purposes of tracking used state objects in a processor function. - -```Lua -- - Value - - state object - since v0.2 - -
- -Stores a single value which can be updated at any time. - -```Lua -( - initialValue: T -) -> Value- since v0.2 -
- -### :octicons-code-24: Value:set() - -Replaces the currently stored value, updating any other state objects that -depend on this value object. The value is stored directly, and no cloning or -alteration is done. - -If the new value is the same as the old value, other state objects won't be -updated. - -```Lua -(newValue: T) -> () -``` - -#### Parameters - -- `newValue` - The new value to be stored. - -??? note "Table sameness" - Updates are always sent out when setting a table value, because it's much - more difficult to evaluate if two tables are the same. Therefore, this - method is conservative and labels all tables as different, even - compared to themselves. - -??? caution "Legacy parameter: force" - Originally, a second `force` parameter was available in Fusion 0.1 so that - updates could forcibly be sent out, even when the new value was the same as - the old value. This is because Fusion 0.1 used equality to evaluate sameness - for all data types, including tables. This was problematic as many users - attempted to get the table value, modify it, and `:set()` it back into the - object, which would not cause an update as the table reference did not - change. - - Fusion 0.2 uses a different sameness definition for tables to alleviate this - problem. As such, there is no longer a good reason to use this parameter, - and so it is not currently recommended for use. For backwards compatibility, - it will remain for the time being, but do not depend on it for new work. - ------ - -## Example Usage - -```Lua -local numCoins = Value(50) -- start off with 50 coins -print(peek(numCoins)) --> 50 - -numCoins:set(10) -print(peek(numCoins)) --> 10 -``` \ No newline at end of file diff --git a/docs/assets/404-dark.svg b/docs/assets/404-dark.svg new file mode 100644 index 000000000..4236207d4 --- /dev/null +++ b/docs/assets/404-dark.svg @@ -0,0 +1,16 @@ + diff --git a/docs/assets/404-light.svg b/docs/assets/404-light.svg new file mode 100644 index 000000000..0a69ff624 --- /dev/null +++ b/docs/assets/404-light.svg @@ -0,0 +1,16 @@ + diff --git a/docs/assets/404.svg b/docs/assets/404.svg deleted file mode 100644 index 16d14df04..000000000 --- a/docs/assets/404.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/docs/assets/overrides/404.html b/docs/assets/overrides/404.html index 59ac717f1..390cf5bbf 100644 --- a/docs/assets/overrides/404.html +++ b/docs/assets/overrides/404.html @@ -2,31 +2,54 @@ {% block content %} -
+ ?,
- LayoutOrder: CanBeState?,
- Position: CanBeState?,
- AnchorPoint: CanBeState?,
- Size: CanBeState?,
- AutomaticSize: CanBeState?,
- ZIndex: CanBeState?,
-
- -- button-specific properties
- Text: CanBeState?,
- OnClick: (() -> ())?,
- Disabled: CanBeState?
-}
-
--- Returns `Child` to match Fusion's `Component` type. This should work for most
--- use cases, and offers the greatest encapsulation as you're able to swap out
--- your return type for an array or state object if you want to.
-local function Button(props: Props): Child
- -- We should generally be careful about storing state in widely reused
- -- components, as the Tutorials explain, but for contained use cases such as
- -- hover states, it should be perfectly fine.
- local isHovering = Value(false)
- local isHeldDown = Value(false)
-
- return New "TextButton" {
+local Fusion = -- initialise Fusion here however you please!
+local scoped = Fusion.scoped
+local Children, OnEvent = Fusion.Children, Fusion.OnEvent
+
+local COLOUR_BLACK = Color3.new(0, 0, 0)
+local COLOUR_WHITE = Color3.new(1, 1, 1)
+
+local COLOUR_TEXT = COLOUR_WHITE
+local COLOUR_BG_REST = Color3.fromHex("0085FF")
+local COLOUR_BG_HOVER = COLOUR_BG_REST:Lerp(COLOUR_WHITE, 0.25)
+local COLOUR_BG_HELD = COLOUR_BG_REST:Lerp(COLOUR_BLACK, 0.25)
+local COLOUR_BG_DISABLED = Color3.fromHex("CCCCCC")
+
+local BG_FADE_SPEED = 20 -- spring speed units
+
+local ROUNDED_CORNERS = UDim.new(0, 4)
+local PADDING = UDim2.fromOffset(6, 4)
+
+local function Button(
+ scope: Fusion.Scope,
+ props: {
+ Name: Fusion.CanBeState?,
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ AutomaticSize: Fusion.CanBeState?
+ },
+ Text: Fusion.CanBeState?,
+ Disabled: Fusion.CanBeState?,
+ OnClick: (() -> ())?
+ }
+): Fusion.Child
+ local isHovering = scope:Value(false)
+ local isHeldDown = scope:Value(false)
+
+ return scope:New "TextButton" {
Name = props.Name,
- LayoutOrder = props.LayoutOrder,
- Position = props.Position,
- AnchorPoint = props.AnchorPoint,
- Size = props.Size,
- AutomaticSize = props.AutomaticSize,
- ZIndex = props.ZIndex,
+
+ LayoutOrder = props.Layout.LayoutOrder,
+ Position = props.Layout.Position,
+ AnchorPoint = props.Layout.AnchorPoint,
+ ZIndex = props.Layout.ZIndex,
+ Size = props.Layout.Size,
+ AutomaticSize = props.Layout.AutomaticSize,
Text = props.Text,
- TextColor3 = Color3.fromHex("FFFFFF"),
-
- BackgroundColor3 = Spring(Computed(function(use)
- if use(props.Disabled) then
- return Color3.fromHex("CCCCCC")
- else
- local baseColour = Color3.fromHex("0085FF")
- -- darken/lighten when hovered or held down
- if use(isHeldDown) then
- baseColour = baseColour:Lerp(Color3.new(0, 0, 0), 0.25)
- elseif use(isHovering) then
- baseColour = baseColour:Lerp(Color3.new(1, 1, 1), 0.25)
+ TextColor3 = COLOUR_TEXT,
+
+ BackgroundColor3 = scope:Spring(
+ scope:Computed(function(use)
+ -- The order of conditions matter here; it defines which states
+ -- visually override other states, with earlier states being
+ -- more important.
+ return
+ if use(props.Disabled) then COLOUR_BG_DISABLED
+ elseif use(isHeldDown) then COLOUR_BG_HELD
+ elseif use(isHovering) then COLOUR_BG_HOVER
+ else return COLOUR_BG_REST
end
- return baseColour
- end
- end), 20),
+ end),
+ BG_FADE_SPEED
+ ),
[OnEvent "Activated"] = function()
if props.OnClick ~= nil and not peek(props.Disabled) then
- -- We're explicitly calling this function with no arguments to
- -- match the types we specified above. If we just passed it
- -- straight into the event, the function would receive arguments
- -- from the Activated event, which might not be desirable.
+ -- Explicitly called with no arguments to match the typedef.
+ -- If passed straight to `OnEvent`, the function might receive
+ -- arguments from the event. If the function secretly *does*
+ -- take arguments (despite the type) this would cause problems.
props.OnClick()
end
end,
[OnEvent "MouseButton1Down"] = function()
- isHeldDown:set(true) -- it's good UX to give immediate feedback
+ isHeldDown:set(true)
end,
-
[OnEvent "MouseButton1Up"] = function()
isHeldDown:set(false)
end,
[OnEvent "MouseEnter"] = function()
-- Roblox calls this event even if the button is being covered by
- -- other UI. For simplicity, we won't worry about that.
+ -- other UI. For simplicity, this does not account for that.
isHovering:set(true)
end,
-
[OnEvent "MouseLeave"] = function()
- isHovering:set(false)
-- If the button is being held down, but the cursor moves off the
-- button, then we won't receive the mouse up event. To make sure
-- the button doesn't get stuck held down, we'll release it if the
-- cursor leaves the button.
isHeldDown:set(false)
+ isHovering:set(false)
end,
[Children] = {
New "UICorner" {
- CornerRadius = UDim.new(0, 4)
+ CornerRadius = ROUNDED_CORNERS
},
New "UIPadding" {
- PaddingTop = UDim.new(0, 6),
- PaddingBottom = UDim.new(0, 6),
- PaddingLeft = UDim.new(0, 6),
- PaddingRight = UDim.new(0, 6)
+ PaddingTop = PADDING.Y,
+ PaddingBottom = PADDING.Y,
+ PaddingLeft = PADDING.X,
+ PaddingRight = PADDING.X
}
}
}
end
return Button
-```
\ No newline at end of file
+```
+
+-----
+
+## Explanation
+
+The main part of note is the function signature. It's highly recommended that
+you statically type the function signature for components, because it not only
+improves autocomplete and error checking, but also acts as up-to-date, machine
+readable documentation.
+
+```Lua
+local function Button(
+ scope: Fusion.Scope,
+ props: {
+ Name: Fusion.CanBeState?,
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ AutomaticSize: Fusion.CanBeState?
+ },
+ Text: Fusion.CanBeState?,
+ Disabled: Fusion.CanBeState?,
+ OnClick: (() -> ())?
+ }
+): Fusion.Child
+```
+
+The `scope` parameter specifies that the component depends on Fusion's methods.
+If you're not sure how to write type definitions for scopes,
+[the 'Scopes' section of the Components tutorial](../../../tutorials/components/components/#scopes)
+goes into further detail.
+
+The property table is laid out with each property on a new line, so it's easy to
+scan the list and see what properties are available. Most are `CanBeState`,
+which allows the user to use state objects if they desire. They're also `?`
+(optional), which can reduce boilerplate when using the component. Not all
+properties have to be that way, but usually it's better to have the flexibility.
+
+!!! tip "Property grouping"
+ You can group properties together in nested tables, like the `Layout` table
+ above, to avoid long mixed lists of properties. In addition to being more
+ readable, this can sometimes help with passing around lots of properties at
+ once, because you can pass the whole nested table as one value if you'd like
+ to.
+
+The return type of the function is `Fusion.Child`, which tells the user that the
+component is compatible with Fusion's `[Children]` API, without exposing what
+children it's returning specifically. This helps ensure the user doesn't
+accidentally depend on the internal structure of the component.
\ No newline at end of file
diff --git a/docs/examples/cookbook/drag-and-drop.md b/docs/examples/cookbook/drag-and-drop.md
index 2f4ede297..e274566c9 100644
--- a/docs/examples/cookbook/drag-and-drop.md
+++ b/docs/examples/cookbook/drag-and-drop.md
@@ -1,223 +1,152 @@
+This example shows a full drag-and-drop implementation for mouse input only,
+using Fusion's Roblox API.
+
+To ensure best accessibility, any interactions you implement shouldn't force you
+to hold the mouse button down. Either allow drag-and-drop with single clicks, or
+provide a non-dragging alternative. This ensures people with reduced motor
+ability aren't locked out of UI functions.
+
```Lua linenums="1"
-local GuiService = game:GetService("GuiService")
-local HttpService = game:GetService("HttpService")
+local Players = game:GetService("Players")
local UserInputService = game:GetService("UserInputService")
--- [Fusion imports omitted for clarity]
-
--- This example shows a full drag-and-drop implementation for mouse input only.
--- Extending this system to generically work with other input types, such as
--- touch gestures or gamepads, is left as an exercise to the reader. However, it
--- should robustly support dragging many types of UI around flexibly.
-
--- To ensure best accessibility, any interactions you implement shouldn't force
--- the player to hold the mouse button down. Either allow drag-and-drop using
--- single inputs, or provide a non-dragging alternative; this will ensure that
--- players with reduced motor ability aren't locked out of UI functions.
-
--- We're going to need to account for the UI inset sometimes. We cache it here.
-local TOP_LEFT_INSET = GuiService:GetGuiInset()
-
--- To reflect the current position of the cursor on-screen, we'll use a state
--- object that's updated using UserInputService.
-local mousePos = Value(UserInputService:GetMouseLocation() - TOP_LEFT_INSET)
-local mousePosConn = UserInputService.InputChanged:Connect(function(inputObject)
- if inputObject.UserInputType == Enum.UserInputType.MouseMovement then
- mousePos:set(Vector2.new(inputObject.Position.X, inputObject.Position.Y))
- end
-end)
-
--- We need to keep drag of which item is currently being dragged. Only one item
--- can be dragged at a time. This type stores all the information needed:
-export type CurrentlyDragging = {
- -- Each draggable item will have a unique ID; the ID stored here represents
- -- which item is being dragged right now. We'll use strings for this, but
- -- you could use numbers if that's more convenient for you.
- id: string,
- -- When a drag is started, we store the mouse's offset relative to the item
- -- being dragged. When the mouse moves, we can then apply the same offset to
- -- make it look like the item is 'pinned' to the cursor.
- offset: Vector2
-}
--- This state object stores the above during a drag, or `nil` when not dragging.
-local currentlyDragging: Value = Value(nil)
-
--- Now we need a component to encapsulate all of our dragging behaviour, such
--- as moving our UI between different parents, placing it at the mouse cursor,
--- managing sizing, and so on.
-
-export type DraggableProps = {
- -- This should uniquely identify the draggable item apart from all other
- -- draggable items. This is constant and so shouldn't be a state object.
- ID: string,
- -- It doesn't make sense for a draggable item to have a constant parent. You
- -- wouldn't be able to drop it anywhere else, so we enforce that Parent is a
- -- state object for our own convenience.
- Parent: StateObject,
- -- When an item is being dragged, it needs to appear above all other UI. We
- -- will create an overlay frame that fills the screen to achieve this.
- OverlayFrame: Instance,
- -- To start a drag, we'll need to know where the top-left corner of the item
- -- is, so we can calculate `currentlyDragging.offset`. We'll allow the
- -- calling code to pass through a Value object to [Out "AbsolutePosition"].
- OutAbsolutePosition: Value?,
-
- Name: CanBeState?,
- LayoutOrder: CanBeState?,
- Position: CanBeState?,
- AnchorPoint: CanBeState?,
- Size: CanBeState?,
- AutomaticSize: CanBeState?,
- ZIndex: CanBeState?,
- [Children]: Child
-}
-local function Draggable(props: DraggableProps): Child
- -- If we need something to be cleaned up when our item is destroyed, we can
- -- add it to this array. It'll be passed to `[Cleanup]` later.
- local cleanupTasks = {}
+local Fusion = -- initialise Fusion here however you please!
+local scoped = Fusion.scoped
+local Children, OnEvent = Fusion.Children, Fusion.OnEvent
- -- This acts like `currentlyDragging`, but filters out anything without a
- -- matching ID, so it'll only exist when this specific item is dragged.
- local thisDragging = Computed(function(use)
- local dragInfo = use(currentlyDragging)
- return if dragInfo ~= nil and dragInfo.id == props.ID then dragInfo else nil
- end)
+type DragInfo = {
+ id: string,
+ mouseOffset: Vector2 -- relative to the dragged item
+}
- -- Our item controls its own parent - one of the few times you'll see this
- -- done in Fusion. This means we don't have to destroy and re-build the item
- -- when it moves to a new location.
- local itemParent = Computed(function(use)
- return if use(thisDragging) ~= nil then props.OverlayFrame else use(props.Parent)
- end, Fusion.doNothing)
-
- -- If we move a scaled UI into the `overlayBox`, by default it will stretch
- -- to the screen size. Ideally we want it to preserve its current size while
- -- it's being dragged, so we need to track the parent's size and calculate
- -- the item size ourselves.
-
- -- To start with, we'll store the parent's absolute size. This takes a bit
- -- of legwork to get right, and we need to remember the UI might not have a
- -- parent which we can measure the size of - we'll represent that as `nil`.
- -- Feel free to extract this into a separate function if you want to.
- local parentSize = Value(nil)
+local function Draggable(
+ scope: Fusion.Scope,
+ props: {
+ ID: string,
+ Name: Fusion.CanBeState?,
+ Parent: Fusion.StateObject, -- StateObject so it's observable
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ OutAbsolutePosition: Fusion.Value?,
+ },
+ Dragging: {
+ MousePosition: Fusion.CanBeState,
+ SelfDragInfo: Fusion.CanBeState,
+ OverlayFrame: Fusion.CanBeState
+ }
+ [typeof(Children)]: Fusion.Child
+ }
+): Fusion.Child
+ -- When `nil`, the parent can't be measured for some reason.
+ local parentSize = scope:Value(nil)
do
- -- We'll call this whenever the parent's AbsoluteSize changes, or when
- -- the parent changes (because different parents might have different
- -- absolute sizes, if any)
- local function recalculateParentSize()
+ local function measureParentNow()
local parent = peek(props.Parent)
- local parentHasSize = parent ~= nil and parent:IsA("GuiObject")
- parentSize:set(if parentHasSize then parent.AbsoluteSize else nil)
+ parentSize:set(
+ if parent ~= nil and parent:IsA("GuiObject")
+ then parent.AbsoluteSize
+ else nil
+ )
end
-
- -- We don't just need to connect to the AbsoluteSize changed event of
- -- the parent we have *right now*! If the parent changes, we need to
- -- disconnect the old event and re-connect on the new parent, which we
- -- do here.
- local parentSizeConn = nil
- local function rebindToParentSize()
- if parentSizeConn ~= nil then
- parentSizeConn:Disconnect()
- parentSizeConn = nil
+ local resizeConn = nil
+ local function stopMeasuring()
+ if resizeConn ~= nil then
+ resizeConn:Disconnect()
+ resizeConn = nil
end
- local parent = peek(props.Parent)
- local parentHasSize = parent ~= nil and parent:IsA("GuiObject")
- if parentHasSize then
- parentSizeConn = parent:GetPropertyChangedSignal("AbsoluteSize"):Connect(recalculateParentSize)
- end
- recalculateParentSize()
end
- local disconnect = Observer(props.Parent):onBind(rebindToParentSize)
-
- -- When the item gets destroyed, we need to disconnect that observer and
- -- our AbsoluteSize change event (if any is active right now)
- table.insert(cleanupTasks, function()
- disconnect()
- if parentSizeConn ~= nil then
- parentSizeConn:Disconnect()
- parentSizeConn = nil
+ scope:Observer(props.Parent):onBind(function()
+ stopMeasuring()
+ measureParentNow()
+ if peek(parentSize) ~= nil then
+ resizeConn = parent:GetPropertyChangedSignal("AbsoluteSize")
+ :Connect(measureParentNow)
end
end)
+ table.insert(scope, stopMeasuring)
end
- -- Now that we have a reliable parent size, we can calculate the item's size
- -- without worrying about all of those event connections.
- local itemSize = Computed(function(use)
- local udim2 = use(props.Size) or UDim2.fromOffset(0, 0)
- local scaleSize = use(parentSize) or Vector2.zero -- might be nil!
- return UDim2.fromOffset(
- udim2.X.Scale * scaleSize.X + udim2.X.Offset,
- udim2.Y.Scale * scaleSize.Y + udim2.Y.Offset
- )
- end)
-
- -- Similarly, we'll need to override the item's position while it's being
- -- dragged. Happily, this is simpler to do :)
- local itemPosition = Computed(function(use)
- local dragInfo = use(thisDragging)
- if dragInfo == nil then
- return use(props.Position) or UDim2.fromOffset(0, 0)
- else
- -- `dragInfo.offset` stores the distance from the top-left corner
- -- of the item to the mouse position. Subtracting the offset from
- -- the mouse position therefore gives us the item's position.
- local position = use(mousePos) - dragInfo.offset
- return UDim2.fromOffset(position.X, position.Y)
- end
- end)
-
return New "Frame" {
Name = props.Name or "Draggable",
- LayoutOrder = props.LayoutOrder,
- AnchorPoint = props.AnchorPoint,
- AutomaticSize = props.AutomaticSize,
- ZIndex = props.ZIndex,
-
- Parent = itemParent,
- Position = itemPosition,
- Size = itemSize,
+ Parent = scope:Computed(function(use)
+ return
+ if use(props.Dragging.SelfDragInfo) ~= nil
+ then use(props.Dragging.OverlayFrame)
+ else use(props.Parent)
+ end),
+
+ LayoutOrder = props.Layout.LayoutOrder,
+ AnchorPoint = props.Layout.AnchorPoint,
+ ZIndex = props.Layout.ZIndex,
+ AutomaticSize = props.Layout.AutomaticSize,
BackgroundTransparency = 1,
- [Out "AbsolutePosition"] = props.OutAbsolutePosition,
+ Position = scope:Computed(function(use)
+ local dragInfo = use(props.Dragging.SelfDragInfo)
+ if dragInfo == nil then
+ return use(props.Layout.Position) or UDim2.fromOffset(0, 0)
+ else
+ local mousePos = use(props.Dragging.MousePosition)
+ local topLeftCorner = mousePos - dragInfo.mouseOffset
+ return UDim2.fromOffset(topLeftCorner.X, topLeftCorner.Y)
+ end
+ end),
+ -- Calculated manually so the Scale can be set relative to
+ -- `props.Parent` at all times, rather than the `Parent` of this Frame.
+ Size = scope:Computed(function(use)
+ local udim2 = use(props.Layout.Size) or UDim2.fromOffset(0, 0)
+ local parentSize = use(parentSize) or Vector2.zero
+ return UDim2.fromOffset(
+ udim2.X.Scale * parentSize.X + udim2.X.Offset,
+ udim2.Y.Scale * parentSize.Y + udim2.Y.Offset
+ )
+ end),
+ [Out "AbsolutePosition"] = props.OutAbsolutePosition,
[Children] = props[Children]
}
end
--- The hard part is over! Now we just need to create some draggable items and
--- start/stop drags in response to mouse events. We'll use a very basic example.
+local COLOUR_COMPLETED = Color3.new(0, 1, 0)
+local COLOUR_NOT_COMPLETED = Color3.new(1, 1, 1)
+
+local TODO_ITEM_SIZE = UDim2.new(1, 0, 0, 50)
--- Let's make some to-do items. They'll show up in two lists - one for
--- incomplete tasks, and another for complete tasks. You'll be able to drag
--- items between the lists to mark them as complete. The lists will be sorted
--- alphabetically so we don't have to deal with calculating where the items
--- should be placed when they're dropped.
+local function newUniqueID()
+ -- You can replace this with a better method for generating unique IDs.
+ return game:GetService("HttpService"):GenerateGUID()
+end
-export type TodoItem = {
+type TodoItem = {
id: string,
text: string,
- completed: Value
+ completed: Fusion.Value
}
-local todoItems: Value = {
+local todoItems: Fusion.Value = {
{
- -- You can use HttpService to easily generate unique IDs statelessly.
- id = HttpService:GenerateGUID(),
+ id = newUniqueID(),
text = "Wake up today",
completed = Value(true)
},
{
- id = HttpService:GenerateGUID(),
+ id = newUniqueID(),
text = "Read the Fusion docs",
completed = Value(true)
},
{
- id = HttpService:GenerateGUID(),
+ id = newUniqueID(),
text = "Take over the universe",
completed = Value(false)
}
}
-local function getTodoItemForID(id: string): TodoItem?
+local function getTodoItemForID(
+ id: string
+): TodoItem?
for _, item in todoItems do
if item.id == id then
return item
@@ -226,192 +155,550 @@ local function getTodoItemForID(id: string): TodoItem?
return nil
end
--- These represent the individual draggable to-do item entries in the lists.
--- This is where we'll use our `Draggable` component!
-export type TodoEntryProps = {
- Item: TodoItem,
- Parent: StateObject,
- OverlayFrame: Instance,
-}
-local function TodoEntry(props: TodoEntryProps): Child
- local absolutePosition = Value(nil)
-
- -- Using our item's ID, we can figure out if we're being dragged to apply
- -- some styling for dragged items only!
- local isDragging = Computed(function(use)
- local dragInfo = use(currentlyDragging)
+local function TodoEntry(
+ outerScope: Fusion.Scope<{}>,
+ props: {
+ Item: TodoItem,
+ Parent: Fusion.StateObject,
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ OutAbsolutePosition: Fusion.Value?,
+ },
+ Dragging: {
+ MousePosition: Fusion.CanBeState,
+ SelfDragInfo: Fusion.CanBeState,
+ OverlayFrame: Fusion.CanBeState?
+ },
+ OnMouseDown: () -> ()?
+ }
+): Fusion.Child
+ local scope = scoped(Fusion, {
+ Draggable = Draggable
+ })
+ table.insert(outerScope, scope)
+
+ local itemPosition = scope:Value(nil)
+ local itemIsDragging = scope:Computed(function(use)
+ local dragInfo = use(props.CurrentlyDragging)
return dragInfo ~= nil and dragInfo.id == props.Item.id
end)
- return Draggable {
+ return scope:Draggable {
ID = props.Item.id,
- Parent = props.Parent,
- OverlayFrame = props.OverlayFrame,
- OutAbsolutePosition = absolutePosition,
-
Name = props.Item.text,
- Size = UDim2.new(1, 0, 0, 50),
+ Parent = props.Parent,
+ Layout = props.Layout,
+ Dragging = props.Dragging,
- [Children] = New "TextButton" {
+ [Children] = scope:New "TextButton" {
Name = "TodoEntry",
Size = UDim2.fromScale(1, 1),
- BackgroundColor3 = Computed(function(use)
- if use(isDragging) then
- return Color3.new(1, 1, 1)
- elseif use(props.Item.completed) then
- return Color3.new(0, 1, 0)
- else
- return Color3.new(1, 0, 0)
+ BackgroundColor3 = scope:Computed(function(use)
+ return
+ if use(props.Item.completed)
+ then COLOUR_COMPLETED
+ else COLOUR_NOT_COMPLETED
end
end),
Text = props.Item.text,
TextSize = 28,
+
+ [OnEvent "MouseButton1Down"] = props.OnMouseDown
- -- This is where we'll detect mouse down. When the mouse is pressed
- -- over this item, we should pick it up.
- [OnEvent "MouseButton1Down"] = function()
- -- only start a drag if we're not already dragging
- if peek(currentlyDragging) == nil then
- local itemPos = peek(absolutePosition) or Vector2.zero
- local offset = peek(mousePos) - itemPos
- currentlyDragging:set({
- id = props.Item.id,
- offset = offset
- })
- end
- end
-
- -- We're not going to detect mouse up here, because in some rare
- -- cases the event could be dropped due to lag between the item's
- -- position and the cursor position. We'll deal with this at a
- -- global level instead.
+ -- Don't detect mouse up here, because in some rare cases, the event
+ -- could be missed due to lag between the item's position and the
+ -- cursor position.
}
}
end
--- Now we should construct our two task lists for housing our to-do entries.
--- Notice that they don't manage the entries themselves! The entries don't
--- belong to these lists after all, so that'd be nonsense :)
+-- Don't forget to pass this to `doCleanup` if you disable the script.
+local scope = scoped(Fusion)
--- When we release our mouse, we need to know where to drop any dragged item we
--- have. This will tell us if we're hovering over either list.
-local dropAction = Value(nil)
+local mousePos = scope:Value(UserInputService:GetMouseLocation())
+table.insert(scope,
+ UserInputService.InputChanged:Connect(function(inputObject)
+ if inputObject.UserInputType == Enum.UserInputType.MouseMovement then
+ -- If this code did not read coordinates from the same method, it
+ -- might inconsistently handle UI insets. So, keep it simple!
+ mousePos:set(UserInputService:GetMouseLocation())
+ end
+ end)
+)
-local incompleteList = New "ScrollingFrame" {
- Name = "IncompleteTasks",
- Position = UDim2.fromScale(0.1, 0.1),
- Size = UDim2.fromScale(0.35, 0.9),
+local dropAction = scope:Value(nil)
- BackgroundTransparency = 0.75,
- BackgroundColor3 = Color3.new(1, 0, 0),
+local taskLists = scope:ForPairs(
+ {
+ incomplete = "mark-as-incomplete",
+ completed = "mark-as-completed"
+ },
+ function(use, scope, listName, listDropAction)
+ return
+ listName,
+ scope:New "ScrollingFrame" {
+ Name = `TaskList ({listName})`,
+ Position = UDim2.fromScale(0.1, 0.1),
+ Size = UDim2.fromScale(0.35, 0.9),
+
+ BackgroundTransparency = 0.75,
+ BackgroundColor3 = Color3.new(1, 0, 0),
+
+ [OnEvent "MouseEnter"] = function()
+ dropAction:set(listDropAction)
+ end,
+
+ [OnEvent "MouseLeave"] = function()
+ -- A different item might have overwritten this already.
+ if peek(dropAction) == listDropAction then
+ dropAction:set(nil)
+ end
+ end,
+
+ [Children] = {
+ New "UIListLayout" {
+ SortOrder = "Name",
+ Padding = UDim.new(0, 5)
+ }
+ }
+ }
+ end
+)
+
+local overlayFrame = scope:New "Frame" {
+ Size = UDim2.fromScale(1, 1),
+ ZIndex = 10,
+ BackgroundTransparency = 1
+}
- [OnEvent "MouseEnter"] = function()
- dropAction:set("incomplete")
- end,
+local currentlyDragging: Fusion.Value = scope:Value(nil)
+
+local allEntries = scope:ForValues(
+ todoItems,
+ function(use, scope, item)
+ local itemPosition = scope:Value(nil)
+ return scope:TodoEntry {
+ Item = item,
+ Parent = scope:Computed(function(use)
+ return
+ if use(item.completed)
+ then use(taskLists).completed
+ else use(taskLists).incomplete
+ end),
+ Layout = {
+ Size = TODO_ITEM_SIZE,
+ OutAbsolutePosition = itemPosition
+ },
+ Dragging = {
+ MousePosition = mousePos,
+ SelfDragInfo = scope:Computed(function(use)
+ local dragInfo = use(currentlyDragging)
+ return
+ if dragInfo == nil or dragInfo.id ~= item.id
+ then nil
+ else dragInfo
+ end)
+ OverlayFrame = overlayFrame
+ },
+ OnMouseDown = function()
+ if peek(currentlyDragging) == nil then
+ local itemPos = peek(itemPosition) or Vector2.zero
+ local mouseOffset = peek(mousePos) - itemPos
+ currentlyDragging:set({
+ id = item.id,
+ mouseOffset = mouseOffset
+ })
+ end
+ end
+ }
+ end
+)
- [OnEvent "MouseLeave"] = function()
- if peek(dropAction) == "incomplete" then
- dropAction:set(nil) -- only clear this if it's not overwritten yet
+table.insert(scope,
+ UserInputService.InputEnded:Connect(function(inputObject)
+ if inputObject.UserInputType ~= Enum.UserInputType.MouseButton1 then
+ return
+ end
+ local dragInfo = peek(currentlyDragging)
+ if dragInfo == nil then
+ return
+ end
+ local item = getTodoItemForID(dragInfo.id)
+ local action = peek(dropAction)
+ if item ~= nil then
+ if action == "mark-as-incomplete" then
+ item.completed:set(false)
+ elseif action == "mark-as-completed" then
+ item.completed:set(true)
+ end
end
- end,
+ currentlyDragging:set(nil)
+ end)
+)
+
+local ui = scope:New "ScreenGui" {
+ Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui")
[Children] = {
- New "UIListLayout" {
- SortOrder = "Name",
- Padding = UDim.new(0, 5)
- }
+ overlayFrame,
+ taskLists,
+ -- Don't pass `allEntries` in here - they manage their own parent!
}
}
+```
-local completedList = New "ScrollingFrame" {
- Name = "CompletedTasks",
- Position = UDim2.fromScale(0.55, 0.1),
- Size = UDim2.fromScale(0.35, 0.9),
+------
- BackgroundTransparency = 0.75,
- BackgroundColor3 = Color3.new(0, 1, 0),
+## Explanation
- [OnEvent "MouseEnter"] = function()
- dropAction:set("completed")
- end,
+The basic idea is to create a container which stores the UI you want to drag.
+This container then reparents itself as it gets dragged around between
+different containers.
- [OnEvent "MouseLeave"] = function()
- if peek(dropAction) == "completed" then
- dropAction:set(nil) -- only clear this if it's not overwritten yet
- end
- end,
+The `Draggable` component implements everything necessary to make a seamlessly
+re-parentable container.
- [Children] = {
- New "UIListLayout" {
- SortOrder = "Name",
- Padding = UDim.new(0, 5)
+```Lua linenums="13"
+type DragInfo = {
+ id: string,
+ mouseOffset: Vector2 -- relative to the dragged item
+}
+
+local function Draggable(
+ scope: Fusion.Scope,
+ props: {
+ ID: string,
+ Name: Fusion.CanBeState?,
+ Parent: Fusion.StateObject, -- StateObject so it's observable
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ OutAbsolutePosition: Fusion.Value?,
+ },
+ Dragging: {
+ MousePosition: Fusion.CanBeState,
+ SelfDragInfo: Fusion.CanBeState,
+ OverlayFrame: Fusion.CanBeState
}
+ [typeof(Children)]: Fusion.Child
+ }
+): Fusion.Child
+```
+
+By default, `Draggable` behaves like a regular Frame, parenting itself to the
+`Parent` property and applying its `Layout` properties.
+
+It only behaves specially when `Dragging.SelfDragInfo` is provided. Firstly,
+it reparents itself to `Dragging.OverlayFrame`, so it can be seen in front of
+other UI.
+
+```Lua linenums="66"
+ Parent = scope:Computed(function(use)
+ return
+ if use(props.Dragging.SelfDragInfo) ~= nil
+ then use(props.Dragging.OverlayFrame)
+ else use(props.Parent)
+ end),
+```
+
+Because of this reparenting, `Draggable` has to do some extra work to keep the
+size consistent; it manually calculates the size based on the size of `Parent`,
+so it doesn't change size when moved to `Dragging.OverlayFrame`.
+
+```Lua linenums="90"
+ -- Calculated manually so the Scale can be set relative to
+ -- `props.Parent` at all times, rather than the `Parent` of this Frame.
+ Size = scope:Computed(function(use)
+ local udim2 = use(props.Layout.Size) or UDim2.fromOffset(0, 0)
+ local parentSize = use(parentSize) or Vector2.zero
+ return UDim2.fromOffset(
+ udim2.X.Scale * parentSize.X + udim2.X.Offset,
+ udim2.Y.Scale * parentSize.Y + udim2.Y.Offset
+ )
+ end),
+```
+
+The `Draggable` also needs to snap to the mouse cursor, so it can be moved by
+the user. Ideally, the mouse would stay fixed in position relative to the
+`Draggable`, so there are no abrupt changes in the position of any elements.
+
+As part of `Dragging.SelfDragInfo`, a `mouseOffset` is provided, which describes
+how far the mouse should stay from the top-left corner. So, when setting the
+position of the `Draggable`, that offset can be applied to keep the UI fixed
+in position relative to the mouse.
+
+```Lua linenums="80"
+ Position = scope:Computed(function(use)
+ local dragInfo = use(props.Dragging.SelfDragInfo)
+ if dragInfo == nil then
+ return use(props.Layout.Position) or UDim2.fromOffset(0, 0)
+ else
+ local mousePos = use(props.Dragging.MousePosition)
+ local topLeftCorner = mousePos - dragInfo.mouseOffset
+ return UDim2.fromOffset(topLeftCorner.X, topLeftCorner.Y)
+ end
+ end),
+```
+
+This is all that's needed to make a generic container that can seamlessly move
+between distinct parts of the UI. The rest of the example demonstrates how this
+can be integrated into real world UI.
+
+The example creates a list of `TodoItem` objects, each with a unique ID, text
+message, and completion status. Because we don't expect the ID or text to
+change, they're just constant values. However, the completion status *is*
+expected to change, so that's specified to be a `Value` object.
+
+```Lua linenums="116"
+type TodoItem = {
+ id: string,
+ text: string,
+ completed: Fusion.Value
+}
+local todoItems: Fusion.Value = {
+ {
+ id = newUniqueID(),
+ text = "Wake up today",
+ completed = Value(true)
+ },
+ {
+ id = newUniqueID(),
+ text = "Read the Fusion docs",
+ completed = Value(true)
+ },
+ {
+ id = newUniqueID(),
+ text = "Take over the universe",
+ completed = Value(false)
}
}
+```
+
+The `TodoEntry` component is meant to represent one individual `TodoItem`.
+
+```Lua linenums="149"
+local function TodoEntry(
+ outerScope: Fusion.Scope<{}>,
+ props: {
+ Item: TodoItem,
+ Parent: Fusion.StateObject,
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ OutAbsolutePosition: Fusion.Value?,
+ },
+ Dragging: {
+ MousePosition: Fusion.CanBeState,
+ SelfDragInfo: Fusion.CanBeState,
+ OverlayFrame: Fusion.CanBeState?
+ },
+ OnMouseDown: () -> ()?
+ }
+): Fusion.Child
+```
--- Now we can write a mouse up handler to drop our items.
+Notice that it shares many of the same property groups as `Draggable` - these
+can be passed directly through.
-local mouseUpConn = UserInputService.InputEnded:Connect(function(inputObject)
- if inputObject.UserInputType ~= Enum.UserInputType.MouseButton1 then
- return
- end
- local dragInfo = peek(currentlyDragging)
- if dragInfo == nil then
- return
- end
- local item = getTodoItemForID(dragInfo.id)
- local action = peek(dropAction)
- if item ~= nil then
- if action == "incomplete" then
- item.completed:set(false)
- elseif action == "completed" then
- item.completed:set(true)
- end
+```Lua linenums="181"
+ return scope:Draggable {
+ ID = props.Item.id,
+ Name = props.Item.text,
+ Parent = props.Parent,
+ Layout = props.Layout,
+ Dragging = props.Dragging,
+```
+
+It also provides an `OnMouseDown` callback, which can be used to pick up the
+entry if the mouse is pressed down above the entry. Note the comment about why
+it is *not* desirable to detect mouse-up here; the UI should unconditionally
+respond to mouse-up, even if the mouse happens to briefly leave this element.
+
+```Lua linenums="202"
+ [OnEvent "MouseButton1Down"] = props.OnMouseDown
+
+ -- Don't detect mouse up here, because in some rare cases, the event
+ -- could be missed due to lag between the item's position and the
+ -- cursor position.
+```
+
+Now, the destinations for these entries can be created. To help decide where to
+drop items later, the `dropAction` tracks which destination the mouse is hovered
+over.
+
+```Lua linenums="225"
+local dropAction = scope:Value(nil)
+
+local taskLists = scope:ForPairs(
+ {
+ incomplete = "mark-as-incomplete",
+ completed = "mark-as-completed"
+ },
+ function(use, scope, listName, listDropAction)
+ return
+ listName,
+ scope:New "ScrollingFrame" {
+ Name = `TaskList ({listName})`,
+ Position = UDim2.fromScale(0.1, 0.1),
+ Size = UDim2.fromScale(0.35, 0.9),
+
+ BackgroundTransparency = 0.75,
+ BackgroundColor3 = Color3.new(1, 0, 0),
+
+ [OnEvent "MouseEnter"] = function()
+ dropAction:set(listDropAction)
+ end,
+
+ [OnEvent "MouseLeave"] = function()
+ -- A different item might have overwritten this already.
+ if peek(dropAction) == listDropAction then
+ dropAction:set(nil)
+ end
+ end,
+
+ [Children] = {
+ New "UIListLayout" {
+ SortOrder = "Name",
+ Padding = UDim.new(0, 5)
+ }
+ }
+ }
end
- currentlyDragging:set(nil)
-end)
+)
+```
--- We'll need to construct an overlay frame for our items to live in while they
--- get dragged around.
+This is also where the 'overlay frame' is created, which gives currently-dragged
+UI a dedicated layer above all other UI to freely move around.
-local overlayFrame = New "Frame" {
+```Lua linenums="264"
+local overlayFrame = scope:New "Frame" {
Size = UDim2.fromScale(1, 1),
ZIndex = 10,
BackgroundTransparency = 1
}
+```
+
+Finally, each `TodoItem` is created as a `TodoEntry`. Some state is also created
+to track which entry is being dragged at the moment.
+
+```Lua linenums="270"
+local currentlyDragging: Fusion.Value = scope:Value(nil)
+
+local allEntries = scope:ForValues(
+ todoItems,
+ function(use, scope, item)
+ local itemPosition = scope:Value(nil)
+ return scope:TodoEntry {
+ Item = item,
+```
+
+Each entry dynamically picks one of the two destinations based on its
+completion status.
+
+```Lua linenums="278"
+ Parent = scope:Computed(function(use)
+ return
+ if use(item.completed)
+ then use(taskLists).completed
+ else use(taskLists).incomplete
+ end),
+```
+
+It also provides the information needed by the `Draggable`.
+
+Note that the current drag information is filtered from the `currentlyDragging`
+state so the `Draggable` won't see information about other entries being
+dragged.
+
+```Lua linenums="288"
+ Dragging = {
+ MousePosition = mousePos,
+ SelfDragInfo = scope:Computed(function(use)
+ local dragInfo = use(currentlyDragging)
+ return
+ if dragInfo == nil or dragInfo.id ~= item.id
+ then nil
+ else dragInfo
+ end)
+ OverlayFrame = overlayFrame
+ },
+```
+
+Now it's time to handle starting and stopping the drag.
+
+To begin the drag, this code makes use of the `OnMouseDown` callback. If nothing
+else is being dragged right now, the position of the mouse relative to the item
+is captured. Then, that `mouseOffset` and the `id` of the item are passed into
+the `currentlyDragging` state to indicate this entry is being dragged.
+
+```Lua linenums="299"
+ OnMouseDown = function()
+ if peek(currentlyDragging) == nil then
+ local itemPos = peek(itemPosition) or Vector2.zero
+ local mouseOffset = peek(mousePos) - itemPos
+ currentlyDragging:set({
+ id = item.id,
+ mouseOffset = mouseOffset
+ })
+ end
+ end
+```
--- Let's construct the items themselves! Because we're constructing them at the
--- global level like this, they're only created and destroyed when they're added
--- and removed from the list.
-
-local allEntries = ForValues(todoItems, function(use, item)
- return TodoEntry {
- Item = item,
- Parent = Computed(function()
- return if use(item.completed) then completedList else incompleteList
- end, Fusion.doNothing),
- OverlayFrame = overlayFrame
- }
-end, Fusion.cleanup)
+To end the drag, a global `InputEnded` listener is created, which should
+reliably fire no matter where or when the event occurs.
--- Finally, construct the whole UI :)
+If there's a `dropAction` to take, for example `mark-as-completed`, then that
+action is executed here.
-local ui = New "ScreenGui" {
- Parent = game:GetService("Players").LocalPlayer.PlayerGui,
+In all cases, `currentlyDragging` is cleared, so the entry is no longer dragged.
- [Cleanup] = {
- mousePosConn,
- mouseUpConn
- },
+```Lua linenums="313"
+table.insert(scope,
+ UserInputService.InputEnded:Connect(function(inputObject)
+ if inputObject.UserInputType ~= Enum.UserInputType.MouseButton1 then
+ return
+ end
+ local dragInfo = peek(currentlyDragging)
+ if dragInfo == nil then
+ return
+ end
+ local item = getTodoItemForID(dragInfo.id)
+ local action = peek(dropAction)
+ if item ~= nil then
+ if action == "mark-as-incomplete" then
+ item.completed:set(false)
+ elseif action == "mark-as-completed" then
+ item.completed:set(true)
+ end
+ end
+ currentlyDragging:set(nil)
+ end)
+)
+```
+
+All that remains is to parent the task lists and overlay frames to a UI, so they
+can be seen. Because the `TodoEntry` component manages their own parent, this
+code shouldn't pass in `allEntries` as a child here.
+
+```Lua linenums="335"
+local ui = scope:New "ScreenGui" {
+ Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui")
[Children] = {
overlayFrame,
- incompleteList,
- completedList
-
- -- We don't have to pass `allEntries` in here - they manage their own
- -- parenting thanks to `Draggable` :)
+ taskLists,
+ -- Don't pass `allEntries` in here - they manage their own parent!
}
}
```
\ No newline at end of file
diff --git a/docs/examples/cookbook/fetch-data-from-server.md b/docs/examples/cookbook/fetch-data-from-server.md
index 86d74e483..9506482a5 100644
--- a/docs/examples/cookbook/fetch-data-from-server.md
+++ b/docs/examples/cookbook/fetch-data-from-server.md
@@ -1,56 +1,149 @@
+This code shows how to deal with yielding/blocking code, such as fetching data
+from a server.
+
+Because these tasks don't complete immediately, they can't be directly run
+inside of a `Computed`, so this example provides a robust framework for handling
+this in a way that doesn't corrupt your code.
+
+This example assumes the presence of a Roblox-like `task` scheduler.
+
+-----
+
+## Overview
+
```Lua linenums="1"
--- [Fusion imports omitted for clarity]
+local Fusion = -- initialise Fusion here however you please!
+local scoped = Fusion.scoped
+
+local function fetchUserBio(
+ userID: number
+): string
+ -- pretend this calls out to a server somewhere, causing this code to yield
+ task.wait(1)
+ return "This is the bio for user " .. userID .. "!"
+end
--- This code assumes that there is a RemoteFunction at this location, which
--- accepts a user ID and will return a string with that user's bio text.
--- The server implementation is not shown here.
-local FetchUserBio = game:GetService("ReplicatedStorage").FetchUserBio
+-- Don't forget to pass this to `doCleanup` if you disable the script.
+local scope = scoped(Fusion)
--- Creating a Value object to store the user ID we're currently looking at
-local currentUserID = Value(1670764)
+-- This doesn't have to be a `Value` - any kind of state object works too.
+local currentUserID = scope:Value(1670764)
--- If we could instantly calculate the user's bio text, we could use a Computed
--- here. However, fetching data from the server takes time, which means we can't
--- use Computed without introducing serious consistency errors into our program.
+-- While the bio is loading, this is `nil` instead of a string.
+local currentUserBio: Fusion.Value = scope:Value(nil)
--- Instead, we fall back to using an observer to manually manage our own value:
-local currentUserBio = Value(nil)
--- Using a scope to hide our management code from the rest of the script:
do
- local lastFetchTime = nil
- local function fetch()
- local fetchTime = os.clock()
- lastFetchTime = fetchTime
- currentUserBio:set(nil) -- set to a default value to indicate loading
- task.spawn(function()
- local bio = FetchUserBio:InvokeServer(peek(currentUserID))
- -- If these two are not equal, then that means another fetch was
- -- started while we were waiting for the server to return a value.
- -- In that case, the more recent call will be more up-to-date, so we
- -- shouldn't overwrite it. This adds a nice layer of reassurance,
- -- but if your value doesn't change often, this might be optional.
- if lastFetchTime == fetchTime then
- currentUserBio:set(bio)
- end
+ local fetchInProgress = nil
+ local function performFetch()
+ local userID = peek(currentUserID)
+ currentUserBio:set(nil)
+ if fetchInProgress ~= nil then
+ task.cancel(fetchInProgress)
+ end
+ fetchInProgress = task.spawn(function()
+ currentUserBio:set(fetchUserBio())
+ fetchInProgress = nil
end)
end
+ scope:Observer(currentUserID):onBind(performFetch)
+end
+
+scope:Observer(currentUserBio):onBind(function()
+ local bio = peek(currentUserBio)
+ if bio == nil then
+ print("User bio is loading...")
+ else
+ print("Loaded user bio:", bio)
+ end
+end)
+```
+
+-----
- fetch() -- get the bio for the initial user ID
- -- when the user ID changes, reload the bio
- local disconnect = Observer(currentUserID):onChange(fetch)
+## Explanation
- -- Don't forget to call `disconnect` when you're done with `currentUserBio`.
- -- That's not included in this code snippet, but it's important if you want
- -- to avoid leaking memory.
+If you yield or wait inside of a `Computed`, you can easily corrupt your entire
+program.
+
+However, this example has a function, `fetchUserBio`, that yields.
+
+```Lua linenums="5"
+local function fetchUserBio(
+ userID: number
+): string
+ -- pretend this calls out to a server somewhere, causing this code to yield
+ task.wait(1)
+ return "This is the bio for user " .. userID .. "!"
end
+```
+
+It also has some arbitrary state object, `currentUserID`, that it needs to
+convert into a bio somehow.
--- Now, you can use `currentUserBio` just like any other state object! Note that
--- `nil` is used to represent a bio that hasn't loaded yet, so you'll want to
--- handle that case before passing it into any code that expects a solid value.
+```Lua linenums="15"
+-- This doesn't have to be a `Value` - any kind of state object works too.
+local currentUserID = scope:Value(1670764)
+```
+
+Because `Computed` can't yield, this code has to manually manage a
+`currentUserBio` object, which will store the output of the code in a way that
+can be used by other Fusion objects later.
+
+Notice that the 'loading' state is explicitly documented. It's a good idea to
+be clear and honest when you have no data to show, because it allows other code
+to respond to that case flexibly.
+
+```Lua linenums="18"
+-- While the bio is loading, this is `nil` instead of a string.
+local currentUserBio: Fusion.Value = scope:Value(nil)
+```
+
+To perform the actual fetch, a simple function can be written which calls
+`fetchUserBio` in a separate task. Once it returns a bio, the `currentUserBio`
+can be updated.
+
+To avoid two fetches overwriting each other, any existing fetch task is canceled
+before the new task is created.
+
+```Lua linenums="22"
+ local fetchInProgress = nil
+ local function performFetch()
+ local userID = peek(currentUserID)
+ currentUserBio:set(nil)
+ if fetchInProgress ~= nil then
+ task.cancel(fetchInProgress)
+ end
+ fetchInProgress = task.spawn(function()
+ currentUserBio:set(fetchUserBio())
+ fetchInProgress = nil
+ end)
+ end
+```
+
+Finally, to run this function when the `currentUserID` changes, `performFetch`
+can be added to an `Observer`.
+
+The `onBind` method also runs `performFetch` once at the start of the program,
+so the request is sent out automatically.
+
+```Lua linenums="34"
+scope:Observer(currentUserID):onBind(performFetch)
+```
+
+That's all you need - now, any other Fusion code can read and depend upon
+`currentUserBio` as if it were any other kind of state object. Just remember to
+handle the 'loading' state as well as the successful state.
+
+```Lua linenums="37"
+scope:Observer(currentUserBio):onBind(function()
+ local bio = peek(currentUserBio)
+ if bio == nil then
+ print("User bio is loading...")
+ else
+ print("Loaded user bio:", bio)
+ end
+end)
+```
-local bioLabel = New "TextLabel" {
- Text = Computed(function(use)
- return use(currentUserBio) or "Loading user bio..."
- end)
-}
-```
\ No newline at end of file
+You may wish to expand this code with error handling if `fetchUserBio()` can
+throw errors.
\ No newline at end of file
diff --git a/docs/examples/cookbook/light-and-dark-theme.md b/docs/examples/cookbook/light-and-dark-theme.md
index a9ffb1b27..3aec057e7 100644
--- a/docs/examples/cookbook/light-and-dark-theme.md
+++ b/docs/examples/cookbook/light-and-dark-theme.md
@@ -1,42 +1,88 @@
+This example demonstrates how to create dynamic theme colours using Fusion's
+state objects.
+
+-----
+
+## Overview
+
```Lua linenums="1"
--- [Fusion imports omitted for clarity]
+local Fusion = --initialise Fusion here however you please!
+local scoped = Fusion.scoped
--- Defining some theme colours. Something to note; I'm intentionally putting the
--- actual colour names as the topmost keys here, and putting `light` and `dark`
--- keys inside the colours. If you did it the other way around, then there's no
--- single source of truth for what colour names are available, and it's hard to
--- keep in sync. If a theme doesn't have a colour, it's better to explicitly not
--- specify it under the colour name.
+local Theme = {}
-local THEME_COLOURS = {
+Theme.colours = {
background = {
light = Color3.fromHex("FFFFFF"),
- dark = Color3.fromHex("2D2D2D")
+ dark = Color3.fromHex("222222")
},
text = {
- light = Color3.fromHex("2D2D2D"),
+ light = Color3.fromHex("222222"),
dark = Color3.fromHex("FFFFFF")
- },
- -- [etc, for all the colours you'd want]
+ }
}
--- This will control which colours we're using at the moment. You could expose
--- this to the rest of your code directly, or calculate it using a Computed.
-local currentTheme = Value("light")
+-- Don't forget to pass this to `doCleanup` if you disable the script.
+local scope = scoped(Fusion)
--- Now we'll create a Computed for every theme colour, which will pick a colour
--- from `THEME_COLS` based on our `currentTheme`.
-local currentColours = {}
-for colourName, colourOptions in THEME_COLOURS do
- currentColours[colourName] = Computed(function(use)
- return colourOptions[use(currentTheme)]
+Theme.current = scope:Value("light")
+Theme.dynamic = {}
+for colour, variants in Theme.colours do
+ Theme.dynamic[colour] = scope:Computed(function(use)
+ return variants[use(Theme.current)]
end)
end
--- Now you can expose `colourOptions` to the rest of your code, preferably under
--- a convenient name :)
+Theme.current:set("light")
+print(peek(Theme.dynamic.background)) --> 255, 255, 255
+
+Theme.current:set("dark")
+print(peek(Theme.dynamic.background)) --> 34, 34, 34
+```
+
+-----
-local text = New "TextLabel" {
- TextColor3 = currentColours.text
+## Explanation
+
+To begin, this example defines a set of colours with light and dark variants.
+
+```Lua linenums="6"
+Theme.colours = {
+ background = {
+ light = Color3.fromHex("FFFFFF"),
+ dark = Color3.fromHex("222222")
+ },
+ text = {
+ light = Color3.fromHex("222222"),
+ dark = Color3.fromHex("FFFFFF")
+ }
}
+```
+
+A `Value` object stores which variant is in use right now.
+
+```Lua linenums="20"
+Theme.current = scope:Value("light")
+```
+
+Finally, each colour is turned into a `Computed`, which dynamically pulls the
+desired variant from the list.
+
+```Lua linenums="21"
+Theme.dynamic = {}
+for colour, variants in Theme.colours do
+ Theme.dynamic[colour] = scope:Computed(function(use)
+ return variants[use(Theme.current)]
+ end)
+end
+```
+
+This allows other code to easily access theme colours from `Theme.dynamic`.
+
+```Lua linenums="28"
+Theme.current:set("light")
+print(peek(Theme.dynamic.background)) --> 255, 255, 255
+
+Theme.current:set("dark")
+print(peek(Theme.dynamic.background)) --> 34, 34, 34
```
\ No newline at end of file
diff --git a/docs/examples/cookbook/loading-spinner.md b/docs/examples/cookbook/loading-spinner.md
index 70e71017b..c944684f2 100644
--- a/docs/examples/cookbook/loading-spinner.md
+++ b/docs/examples/cookbook/loading-spinner.md
@@ -1,39 +1,128 @@
+This example implements a procedural spinning animation using Fusion's Roblox
+APIs.
+
+-----
+
+## Overview
+
```Lua linenums="1"
local RunService = game:GetService("RunService")
--- [Fusion imports omitted for clarity]
-
--- Loading spinners generally don't use transition-based animations like tweens.
--- Instead, they animate continuously and independently, so we'll need to set up
--- our own animation clock that will drive the animation.
--- We can set up one clock and use it everywhere.
-local timer = Value(os.clock())
-local timerConn = RunService.RenderStepped:Connect(function()
- -- Remember to disconnect this event when you're done using it!
- timer:set(os.clock())
-end)
-
--- Our loading spinner will consist of an image which rotates around. You could
--- do something more complex or intricate for spice, but in the interest of
--- providing a simple starting point, let's keep it simple.
-local spinner = New "ImageLabel" {
- Position = UDim2.fromScale(0.5, 0.5),
- AnchorPoint = Vector2.new(0.5, 0.5),
- Size = UDim2.fromOffset(50, 50),
-
- BackgroundTransparency = 1,
- Image = "rbxassetid://your-loading-spinner-image", -- replace this!
-
- -- As the timer runs, this will automatically update and rotate our image.
- Rotation = Computed(function(use)
- local time = use(timer)
- local angle = time * 180 -- Spin at a rate of 180 degrees per second
- angle %= 360 -- Don't need to go beyond 360 degrees; wrap instead
- return angle
- end),
-
- -- If your `timer` is only used by this one loading spinner, you can clean
- -- up the `timerConn` here. If you're re-using one timer for all of your
- -- spinners, you don't need to do this here.
- [Cleanup] = timerConn
+
+local Fusion = -- initialise Fusion here however you please!
+local scoped = Fusion.scoped
+local Children = Fusion.Children
+
+local SPIN_DEGREES_PER_SECOND = 180
+local SPIN_SIZE = 50
+
+local function Spinner(
+ scope: Fusion.Scope,
+ props: {
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?
+ },
+ CurrentTime: Fusion.CanBeState,
+ }
+): Fusion.Child
+ return scope:New "ImageLabel" {
+ Name = "Spinner",
+
+ LayoutOrder = props.Layout.LayoutOrder,
+ Position = props.Layout.Position,
+ AnchorPoint = props.Layout.AnchorPoint,
+ ZIndex = props.Layout.ZIndex,
+
+ Size = UDim2.fromOffset(SPIN_SIZE, SPIN_SIZE),
+
+ BackgroundTransparency = 1,
+ Image = "rbxassetid://your-loading-spinner-image", -- replace this!
+
+ Rotation = scope:Computed(function(use)
+ return (use(props.CurrentTime) * SPIN_DEGREES_PER_SECOND) % 360
+ end)
+ }
+end
+
+-- Don't forget to pass this to `doCleanup` if you disable the script.
+local scope = scoped(Fusion, {
+ Spinner = Spinner
+})
+
+local currentTime = scope:Value(os.clock())
+table.insert(scope,
+ RunService.RenderStepped:Connect(function()
+ currentTime:set(os.clock())
+ end)
+)
+
+local spinner = scope:Spinner {
+ Layout = {
+ Position = UDim2.fromScale(0.5, 0.5),
+ AnchorPoint = Vector2.new(0.5, 0.5),
+ Size = UDim2.fromOffset(50, 50)
+ },
+ CurrentTime = currentTime
+}
+```
+
+-----
+
+## Explanation
+
+The `Spinner` components implements the animation for the loading spinner. It's
+largely a standard Fusion component definition.
+
+The main thing to note is that it asks for a `CurrentTime` property.
+
+```Lua linenums="10" hl_lines="10"
+local function Spinner(
+ scope: Fusion.Scope,
+ props: {
+ Layout: {
+ LayoutOrder: Fusion.CanBeState?,
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ ZIndex: Fusion.CanBeState?
+ },
+ CurrentTime: Fusion.CanBeState,
+ }
+): Fusion.Child
+```
+
+The `CurrentTime` is used to drive the rotation of the loading spinner.
+
+```Lua linenums="35"
+ Rotation = scope:Computed(function(use)
+ return (use(props.CurrentTime) * SPIN_DEGREES_PER_SECOND) % 360
+ end)
+```
+
+That's all that's required for the `Spinner` component.
+
+Later on, the example creates a `Value` object that will store the current time,
+and starts a process to keep it up to date.
+
+```Lua linenums="46"
+local currentTime = scope:Value(os.clock())
+table.insert(scope,
+ RunService.RenderStepped:Connect(function()
+ currentTime:set(os.clock())
+ end)
+)
+```
+
+This can then be passed in as `CurrentTime` when the `Spinner` is created.
+
+```Lua linenums="53" hl_lines="7"
+local spinner = scope:Spinner {
+ Layout = {
+ Position = UDim2.fromScale(0.5, 0.5),
+ AnchorPoint = Vector2.new(0.5, 0.5),
+ Size = UDim2.fromOffset(50, 50)
+ },
+ CurrentTime = currentTime
}
```
\ No newline at end of file
diff --git a/docs/examples/cookbook/player-list.md b/docs/examples/cookbook/player-list.md
index dd169286e..4d4a34102 100644
--- a/docs/examples/cookbook/player-list.md
+++ b/docs/examples/cookbook/player-list.md
@@ -1,47 +1,24 @@
-```Lua linenums="1"
--- [Fusion imports omitted for clarity]
-
-type Set = {[T]: true}
+This shows how to use Fusion's Roblox API to create a simple, dynamically
+updating player list.
--- Defining a component for each row of the player list.
--- Each row represents a player currently logged into the server.
--- We set the `Name` to the player's name so the rows can be sorted by name.
+-----
-type PlayerListRowProps = {
- Player: Player
-}
+## Overview
-local function PlayerListRow(props: PlayerListRowProps)
- return New "TextLabel" {
- Name = props.Player.DisplayName,
-
- Size = UDim2.new(1, 0, 0, 25),
- BackgroundTransparency = 1,
+```Lua linenums="1"
+local Players = game:GetService("Players")
- Text = props.Player.DisplayName,
- TextColor3 = Color3.new(1, 1, 1),
- Font = Enum.Font.GothamMedium,
- FontSize = 16,
- TextXAlignment = "Right",
- TextTruncate = "AtEnd",
+local Fusion = -- initialise Fusion here however you please!
+local scoped = Fusion.scoped
+local Children = Fusion.Children
- [Children] = New "UIPadding" {
- PaddingLeft = UDim.new(0, 10),
- PaddingRight = UDim.new(0, 10)
- }
+local function PlayerList(
+ scope: Fusion.Scope,
+ props: {
+ Players: Fusion.CanBeState<{Player}>
}
-end
-
--- Defining a component for the entire player list.
--- It should take in a set of all logged-in players, and it should be a state
--- object so the set of players can change as players join and leave.
-
-type PlayerListProps = {
- PlayerSet: Fusion.StateObject>
-}
-
-local function PlayerList(props: PlayerListProps)
- return New "Frame" {
+): Fusion.Child
+ return scope:New "Frame" {
Name = "PlayerList",
Position = UDim2.fromScale(1, 0),
@@ -53,53 +30,131 @@ local function PlayerList(props: PlayerListProps)
BackgroundColor3 = Color3.new(0, 0, 0),
[Children] = {
- New "UICorner" {},
- New "UIListLayout" {
+ scope:New "UICorner" {
+ CornerRadius = UDim.new(0, 8)
+ },
+ scope:New "UIListLayout" {
SortOrder = "Name",
FillDirection = "Vertical"
},
- ForPairs(props.PlayerSet, function(use, player, _)
- return player, PlayerListRow {
- Player = player
+ scope:ForValues(props.Players, function(use, scope, player)
+ return scope:New "TextLabel" {
+ Name = "PlayerListRow: " .. player.DisplayName,
+
+ Size = UDim2.new(1, 0, 0, 25),
+ BackgroundTransparency = 1,
+
+ Text = player.DisplayName,
+ TextColor3 = Color3.new(1, 1, 1),
+ Font = Enum.Font.GothamMedium,
+ FontSize = 16,
+ TextXAlignment = "Right",
+ TextTruncate = "AtEnd",
+
+ [Children] = scope:New "UIPadding" {
+ PaddingLeft = UDim.new(0, 10),
+ PaddingRight = UDim.new(0, 10)
+ }
}
- end, Fusion.cleanup)
+ end)
}
}
end
--- To create the PlayerList component, first we need a state object that stores
--- the set of logged-in players, and updates as players join and leave.
-
-local Players = game:GetService("Players")
+-- Don't forget to pass this to `doCleanup` if you disable the script.
+local scope = scoped(Fusion, {
+ PlayerList = PlayerList
+})
-local playerSet = Value()
-local function updatePlayerSet()
- local newPlayerSet = {}
- for _, player in Players:GetPlayers() do
- newPlayerSet[player] = true
- end
- playerSet:set(newPlayerSet)
+local players = scope:Value(Players:GetPlayers())
+local function updatePlayers()
+ players:set(Players:GetPlayers())
end
-local playerConnections = {
- Players.PlayerAdded:Connect(updatePlayerSet),
- Players.PlayerRemoving:Connect(updatePlayerSet)
+table.insert(scope, {
+ Players.PlayerAdded:Connect(updatePlayers),
+ Players.PlayerRemoving:Connect(updatePlayers)
+})
+
+local gui = scope:New "ScreenGui" {
+ Name = "PlayerListGui",
+ Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui"),
+
+ [Children] = scope:PlayerList {
+ Players = players
+ }
}
-updatePlayerSet()
+```
--- Now, we can create the component and pass in `playerSet`.
--- Don't forget to clean up your connections when your UI is destroyed; to do
--- that, we're using the `[Cleanup]` key to clean up `playerConnections` later.
+-----
-local gui = New "ScreenGui" {
+## Explanation
+
+The `PlayerList` component is designed to be simple and self-contained. The only
+thing it needs is a `Players` list - it handles everything else, including its
+position, size, appearance and behaviour.
+
+```Lua linenums="7"
+local function PlayerList(
+ scope: Fusion.Scope,
+ props: {
+ Players: Fusion.CanBeState<{Player}>
+ }
+): Fusion.Child
+```
+
+After creating a vertically expanding Frame with some style and layout added,
+it turns the `Players` into a series of text labels using `ForValues`, which
+will automatically create and remove them as the `Players` list changes.
+
+```Lua linenums="33"
+ scope:ForValues(props.Players, function(use, scope, player)
+ return scope:New "TextLabel" {
+ Name = "PlayerListRow: " .. player.DisplayName,
+
+ Size = UDim2.new(1, 0, 0, 25),
+ BackgroundTransparency = 1,
+
+ Text = player.DisplayName,
+ TextColor3 = Color3.new(1, 1, 1),
+ Font = Enum.Font.GothamMedium,
+ FontSize = 16,
+ TextXAlignment = "Right",
+ TextTruncate = "AtEnd",
+
+ [Children] = scope:New "UIPadding" {
+ PaddingLeft = UDim.new(0, 10),
+ PaddingRight = UDim.new(0, 10)
+ }
+ }
+ end)
+```
+
+That's all that the `PlayerList` component has to do.
+
+Later on, the code creates a `Value` object to store a list of players, and
+update it every time a player joins or leaves the game.
+
+```Lua linenums="62"
+local players = scope:Value(Players:GetPlayers())
+local function updatePlayers()
+ players:set(Players:GetPlayers())
+end
+table.insert(scope, {
+ Players.PlayerAdded:Connect(updatePlayers),
+ Players.PlayerRemoving:Connect(updatePlayers)
+})
+```
+
+That object can then be passed in as `Players` when creating the `PlayerList`.
+
+```Lua linenums="71" hl_lines="6"
+local gui = scope:New "ScreenGui" {
Name = "PlayerListGui",
Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui"),
- [Cleanup] = playerConnections,
-
- [Children] = PlayerList {
- PlayerSet = playerSet
+ [Children] = scope:PlayerList {
+ Players = players
}
}
-
```
\ No newline at end of file
diff --git a/docs/examples/index.md b/docs/examples/index.md
index 5eaa91e4a..be7c9b88a 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -24,7 +24,7 @@ animations and responding to different events.
## Open-Source Projects
-### Fusion Wordle
+### Fusion Wordle (for Fusion 0.2)
@@ -33,7 +33,7 @@ validation, spring animations and sounds.
[Play and edit the game on Roblox.](https://www.roblox.com/games/12178127791/)
-### Fusion Obby
+### Fusion Obby (for Fusion 0.1)
diff --git a/docs/tutorials/animation/springs.md b/docs/tutorials/animation/springs.md
index e6422008c..ed53aa3a2 100644
--- a/docs/tutorials/animation/springs.md
+++ b/docs/tutorials/animation/springs.md
@@ -9,24 +9,17 @@ movement naturally without abrupt changes in direction.
## Usage
-To use `Spring` in your code, you first need to import it from the Fusion
-module, so that you can refer to it by name:
-
-```Lua linenums="1" hl_lines="2"
-local Fusion = require(ReplicatedStorage.Fusion)
-local Spring = Fusion.Spring
-```
-
-To create a new spring object, call the `Spring` function and pass it a state
-object to move towards:
+To create a new spring object, call `scope:Spring()` and pass it a state object
+to move towards:
```Lua
-local goal = Value(0)
-local animated = Spring(target)
+local goal = scope:Value(0)
+local animated = scope:Spring(goal)
```
-The spring will smoothly follow the 'goal' state object over time. As with other
-state objects, you can `peek()` at its value at any time:
+The spring will smoothly follow the 'goal' state object over time.
+
+As with other state objects, you can `peek()` at its value at any time:
```Lua
print(peek(animated)) --> 0.26425...
@@ -36,10 +29,17 @@ To configure how the spring moves, you can provide a speed and damping ratio to
use. Both are optional, and both can be state objects if desired:
```Lua
-local goal = Value(0)
+local goal = scope:Value(0)
local speed = 25
-local damping = Value(0.5)
-local animated = Spring(target, speed, damping)
+local damping = scope:Value(0.5)
+local animated = scope:Spring(goal, speed, damping)
+```
+
+You can also set the position and velocity of the spring at any time.
+
+```Lua
+animated:setPosition(5) -- teleport the spring to 5
+animated:setVelocity(2) -- from here, move 2 units/second
```
You can use many different kinds of values with springs, not just numbers.
@@ -47,8 +47,8 @@ Vectors, CFrames, Color3s, UDim2s and other number-based types are supported;
each number inside the type is animated individually.
```Lua
-local goalPosition = Value(UDim2.new(0.5, 0, 0, 0))
-local animated = Spring(target, 25, 0.5)
+local goalPosition = scope:Value(UDim2.new(0.5, 0, 0, 0))
+local animated = scope:Spring(goalPosition, 25, 0.5)
```
-----
diff --git a/docs/tutorials/animation/tweens.md b/docs/tutorials/animation/tweens.md
index d7a430423..cc7723a3b 100644
--- a/docs/tutorials/animation/tweens.md
+++ b/docs/tutorials/animation/tweens.md
@@ -8,24 +8,17 @@ This can be used for basic, predictable animations.
## Usage
-To use `Tween` in your code, you first need to import it from the Fusion
-module, so that you can refer to it by name:
-
-```Lua linenums="1" hl_lines="2"
-local Fusion = require(ReplicatedStorage.Fusion)
-local Tween = Fusion.Tween
-```
-
-To create a new tween object, call the `Tween` function and pass it a state
-object to move towards:
+To create a new tween object, call `scope:Tween()` and pass it a state object to
+move towards:
```Lua
-local goal = Value(0)
-local animated = Tween(target)
+local goal = scope:Value(0)
+local animated = scope:Tween(goal)
```
-The tween will smoothly follow the 'goal' state object over time. As with other
-state objects, you can `peek()` at its value at any time:
+The tween will smoothly follow the 'goal' state object over time.
+
+As with other state objects, you can `peek()` at its value at any time:
```Lua
print(peek(animated)) --> 0.26425...
@@ -36,9 +29,9 @@ shape of the animation curve. It's optional, and it can be a state object if
desired:
```Lua
-local goal = Value(0)
+local goal = scope:Value(0)
local style = TweenInfo.new(0.5, Enum.EasingStyle.Quad)
-local animated = Tween(target, style)
+local animated = scope:Tween(goal, style)
```
You can use many different kinds of values with tweens, not just numbers.
@@ -46,8 +39,8 @@ Vectors, CFrames, Color3s, UDim2s and other number-based types are supported;
each number inside the type is animated individually.
```Lua
-local goalPosition = Value(UDim2.new(0.5, 0, 0, 0))
-local animated = Tween(target, TweenInfo.new(0.5, Enum.EasingStyle.Quad))
+local goalPosition = scope:Value(UDim2.new(0.5, 0, 0, 0))
+local animated = scope:Tween(goalPosition, TweenInfo.new(0.5, Enum.EasingStyle.Quad))
```
-----
diff --git a/docs/tutorials/components/callbacks.md b/docs/tutorials/best-practices/callbacks.md
similarity index 66%
rename from docs/tutorials/components/callbacks.md
rename to docs/tutorials/best-practices/callbacks.md
index c04e88e15..7a792836e 100644
--- a/docs/tutorials/components/callbacks.md
+++ b/docs/tutorials/best-practices/callbacks.md
@@ -11,17 +11,9 @@ example to report when button clicks occur.
## In Luau
-Callbacks are functions which you pass into other functions. They're part of
-normal Luau code.
-
-```Lua
-workspace.ChildAdded:Connect(function()
- -- this function is a callback!
-end)
-```
-
-They're useful because they allow the function to 'call back' into your code,
-so your code can do something in response:
+Callbacks are functions which you pass into other functions. They're useful
+because they allow the function to 'call back' into your code, so your code can
+do something in response:
```Lua
local function printMessage()
@@ -38,10 +30,12 @@ function. Luau will execute the function, then return to your code.
In this example, the `fiveTimes` function calls a callback five times:
-=== "Script code"
+=== "Luau code"
```Lua
- local function fiveTimes(callback)
+ local function fiveTimes(
+ callback: (number) -> ()
+ )
for x=1, 5 do
callback(x)
end
@@ -69,9 +63,16 @@ In this example, the `fiveTimes` function calls a callback five times:
Components can use callbacks the same way. Consider this button component; when
the button is clicked, the button needs to run some external code:
-```Lua
-local function Button(props)
- return New "TextButton" {
+```Lua hl_lines="17"
+local function Button(
+ scope: Fusion.Scope
+ props: {
+ Position: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ Text: Fusion.CanBeState?
+ }
+)
+ return scope:New "TextButton" {
BackgroundColor3 = Color3.new(0.25, 0.5, 1),
Position = props.Position,
Size = props.Size,
@@ -84,10 +85,10 @@ local function Button(props)
end
```
-It can ask the controlling code to provide a callback in `props`, called OnClick:
+It can ask the controlling code to provide an `OnClick` callback in `props`.
-```Lua hl_lines="3-5"
-local button = Button {
+```Lua
+local button = scope:Button {
Text = "Hello, world!",
OnClick = function()
print("The button was clicked")
@@ -96,11 +97,20 @@ local button = Button {
```
Assuming that callback is passed in, the callback can be passed directly into
-`[OnEvent]`, because `[OnEvent]` accepts functions:
-
-```Lua hl_lines="10"
-local function Button(props)
- return New "TextButton" {
+`[OnEvent]`, because `[OnEvent]` accepts functions. It can even be optional -
+Luau won't add the key to the table if the value is `nil`.
+
+```Lua hl_lines="7 18"
+local function Button(
+ scope: Fusion.Scope,
+ props: {
+ Position: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ Text: Fusion.CanBeState?,
+ OnClick: (() -> ())?
+ }
+)
+ return scope:New "TextButton" {
BackgroundColor3 = Color3.new(0.25, 0.5, 1),
Position = props.Position,
Size = props.Size,
@@ -116,9 +126,18 @@ end
Alternatively, we can call `props.OnClick` manually, which is useful if you want
to do your own processing first:
-```Lua hl_lines="10-15"
-local function Button(props)
- return New "TextButton" {
+```Lua hl_lines="19-23"
+local function Button(
+ scope: Fusion.Scope,
+ props: {
+ Position: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ Text: Fusion.CanBeState?,
+ Disabled: Fusion.CanBeState?,
+ OnClick: (() -> ())?
+ }
+)
+ return scope:New "TextButton" {
BackgroundColor3 = Color3.new(0.25, 0.5, 1),
Position = props.Position,
Size = props.Size,
@@ -127,8 +146,7 @@ local function Button(props)
TextColor3 = Color3.new(1, 1, 1),
[OnEvent "Activated"] = function()
- -- don't send clicks if the button is disabled
- if not peek(props.Disabled) then
+ if props.OnClick ~= nil and not peek(props.Disabled) then
props.OnClick()
end
end
diff --git a/docs/tutorials/components/callbacks/Top-Down-Control-Dark.svg b/docs/tutorials/best-practices/callbacks/Top-Down-Control-Dark.svg
similarity index 100%
rename from docs/tutorials/components/callbacks/Top-Down-Control-Dark.svg
rename to docs/tutorials/best-practices/callbacks/Top-Down-Control-Dark.svg
diff --git a/docs/tutorials/components/callbacks/Top-Down-Control-Light.svg b/docs/tutorials/best-practices/callbacks/Top-Down-Control-Light.svg
similarity index 100%
rename from docs/tutorials/components/callbacks/Top-Down-Control-Light.svg
rename to docs/tutorials/best-practices/callbacks/Top-Down-Control-Light.svg
diff --git a/docs/tutorials/best-practices/components.md b/docs/tutorials/best-practices/components.md
new file mode 100644
index 000000000..f219c47c3
--- /dev/null
+++ b/docs/tutorials/best-practices/components.md
@@ -0,0 +1,340 @@
+You can use functions to create self-contained, reusable blocks of code. In the
+world of UI, you may think of them as *components* - though they can be used for
+much more than just UI.
+
+For example, consider this function, which generates a button based on some
+`props` the user passes in:
+
+```Lua
+local function Button(
+ scope: Fusion.Scope,
+ props: {
+ Position: Fusion.CanBeState?,
+ AnchorPoint: Fusion.CanBeState?,
+ Size: Fusion.CanBeState?,
+ LayoutOrder: Fusion.CanBeState?,
+ ButtonText: Fusion.CanBeState
+ }
+)
+ return scope:New "TextButton" {
+ BackgroundColor3 = Color3.new(0, 0.25, 1),
+ Position = props.Position,
+ AnchorPoint = props.AnchorPoint,
+ Size = props.Size,
+ LayoutOrder = props.LayoutOrder,
+
+ Text = props.ButtonText,
+ TextSize = 28,
+ TextColor3 = Color3.new(1, 1, 1),
+
+ [Children] = UICorner { CornerRadius = UDim2.new(0, 8) }
+ }
+end
+```
+
+You can call this function later to generate as many buttons as you need.
+
+```Lua
+local helloBtn = Button(scope, {
+ ButtonText = "Hello",
+ Size = UDim2.fromOffset(200, 50)
+})
+
+helloBtn.Parent = Players.LocalPlayer.PlayerGui.ScreenGui
+```
+
+Since the `scope` is the first parameter, it can even be used with `scoped()`
+syntax.
+
+```Lua
+local scope = scoped(Fusion, {
+ Button = Button
+})
+
+local helloBtn = scope:Button {
+ ButtonText = "Hello",
+ Size = UDim2.fromOffset(200, 50)
+}
+
+helloBtn.Parent = Players.LocalPlayer.PlayerGui.ScreenGui
+```
+
+This is the primary way of writing components in Fusion. You create functions
+that accept `scope` and `props`, then return some content from them.
+
+-----
+
+## Properties
+
+If you don't say what `props` should contain, it might be hard to figure
+out how to use it.
+
+You can specify your list of properties by adding a type to `props`, which gives
+you useful autocomplete and type checking.
+
+```Lua
+local function Cake(
+ -- ... some stuff here ...
+ props: {
+ Size: Vector3,
+ Colour: Color3,
+ IsTasty: boolean
+ }
+)
+ -- ... some other stuff here ...
+end
+```
+
+Note that the above code only accepts constant values, not state objects. If you
+want to accept *either* a constant or a state object, you can use the
+`CanBeState` type.
+
+```Lua
+local function Cake(
+ -- ... some stuff here ...
+ props: {
+ Size: Fusion.CanBeState,
+ Colour: Fusion.CanBeState,
+ IsTasty: Fusion.CanBeState
+ }
+)
+ -- ... some other stuff here ...
+end
+```
+
+This is usually what you want, because it means the user can easily switch
+a property to dynamically change over time, while still writing properties
+normally when they don't change over time. You can mostly treat `CanBeState`
+properties like they're state objects, because functions like `peek()` and
+`use()` automatically choose the right behaviour for you.
+
+If something *absolutely must* be a state object, you can use the
+`StateObject` type instead. You should only consider this when it doesn't
+make sense for the property to stay the same forever.
+
+```Lua
+local function Cake(
+ -- ... some stuff here ...
+ props: {
+ Size: Fusion.StateObject,
+ Colour: Fusion.StateObject,
+ IsTasty: Fusion.StateObject
+ }
+)
+ -- ... some other stuff here ...
+end
+```
+
+You can use the rest of Luau's type checking features to do more complex
+things, like making certain properties optional, or restricting that values
+are valid for a given property. Go wild!
+
+!!! warning "Be mindful of the angle brackets"
+ Remember that, when working with `StateObject` and `CanBeState`, you should
+ be mindful of whether you're putting things inside the angled brackets, or
+ outside of them. Putting some things inside of the angle brackets can change
+ their meaning, compared to putting them outside of the angle brackets.
+
+ Consider these two type definitions carefully:
+
+ ```Lua
+ -- either nil, or a state object which always stores Vector3
+ Fusion.StateObject?
+
+ -- always a state object, which stores either Vector3 or nil
+ Fusion.StateObject
+ ```
+
+ The first type is best for *optional properties*, where you provide a
+ default value if it isn't specified by the user. If the user *does* specify
+ it, they're forced to always give a valid value for it.
+
+ The second type is best if the property understands `nil` as a valid value.
+ This means the user can set it to `nil` at any time.
+
+-----
+
+## Scopes
+
+In addition to `props`, you should also ask for a `scope`. The `scope`
+parameter should come first, so that your users can use `scoped()` syntax to
+create it.
+
+```Lua
+-- barebones syntax
+local thing = Component(scope, {
+ -- ... some properties here ...
+})
+
+-- scoped() syntax
+local thing = scope:Component {
+ -- ... some properties here ...
+}
+```
+
+It's a good idea to provide a type for `scope`. This lets you specify what
+methods you need the scope to have.
+
+```Lua
+scope: Fusion.Scope
+```
+
+If you don't know what methods to ask for, consider these two strategies.
+
+1. If you only use common methods (like Fusion's constructors) then it's a
+safe assumption that the user will also have those methods. You can ask for a
+scope with those methods pre-defined.
+
+ ```Lua hl_lines="2"
+ local function Component(
+ scope: Fusion.Scope,
+ props: {}
+ )
+ return scope:New "Thing" {
+ -- ... rest of code here ...
+ }
+ end
+ ```
+
+2. If you need more specific or niche things that the user likely won't have
+(for example, components you use internally), then you should not ask for those.
+Instead, create a new inner scope with the methods you need.
+
+ ```Lua hl_lines="2 5-9"
+ local function Component(
+ outerScope: Fusion.Scope<{}>,
+ props: {}
+ )
+ local scope = scoped(Fusion, {
+ SpecialThing1 = require(script.SpecialThing1),
+ SpecialThing2 = require(script.SpecialThing2),
+ })
+ table.insert(outerScope, scope)
+
+ return scope:SpecialThing1 {
+ -- ... rest of code here ...
+ }
+ end
+ ```
+
+If you're not sure which strategy to pick, the second is always a safe fallback,
+because it assumes less about your users and helps hide implementation details.
+
+
+-----
+
+## Modules
+
+It's common to save different components inside of different files.
+There's a number of advantages to this:
+
+- it's easier to find the source code for a specific component
+- it keep each file shorter and simpler
+- it makes sure components are properly independent, and can't interfere
+- it encourages reusing components everywhere, not just in one file
+
+Here's an example of how you could split up some components into modules:
+
+=== "Main file"
+
+ ```Lua linenums="1"
+ local Fusion = require(game:GetService("ReplicatedStorage").Fusion)
+ local scoped, doCleanup = Fusion.scoped, Fusion.doCleanup
+
+ local scope = scoped(Fusion, {
+ PopUp = require(script.Parent.PopUp)
+ })
+
+ local ui = scope:New "ScreenGui" {
+ -- ...some properties...
+
+ [Children] = scope:PopUp {
+ Message = "Hello, world!",
+ DismissText = "Close"
+ }
+ }
+ ```
+=== "PopUp"
+
+ ```Lua linenums="1"
+ local Fusion = require(game:GetService("ReplicatedStorage").Fusion)
+
+ local function PopUp(
+ outerScope: Fusion.Scope<{}>,
+ props: {
+ Message: Fusion.CanBeState,
+ DismissText: Fusion.CanBeState
+ }
+ )
+ local scope = scoped(Fusion, {
+ Message = require(script.Parent.Message),
+ Button = require(script.Parent.Button)
+ })
+ table.insert(outerScope, scope)
+
+ return scope:New "Frame" {
+ -- ...some properties...
+
+ [Children] = {
+ scope:Message {
+ Scope = scope,
+ Text = props.Message
+ }
+ scope:Button {
+ Scope = scope,
+ Text = props.DismissText
+ }
+ }
+ }
+ end
+
+ return PopUp
+ ```
+
+=== "Message"
+
+ ```Lua linenums="1"
+ local Fusion = require(game:GetService("ReplicatedStorage").Fusion)
+
+ local function Message(
+ scope: Fusion.Scope,
+ props: {
+ Text: Fusion.CanBeState
+ }
+ )
+ return scope:New "TextLabel" {
+ AutomaticSize = "XY",
+ BackgroundTransparency = 1,
+
+ -- ...some properties...
+
+ Text = props.Text
+ }
+ end
+
+ return Message
+ ```
+
+=== "Button"
+
+ ```Lua linenums="1"
+ local Fusion = require(game:GetService("ReplicatedStorage").Fusion)
+
+ local function Button(
+ scope: Fusion.Scope,
+ props: {
+ Text: Fusion.CanBeState
+ }
+ )
+ return scope:New "TextButton" {
+ BackgroundColor3 = Color3.new(0.25, 0.5, 1),
+ AutoButtonColor = true,
+
+ -- ...some properties...
+
+ Text = props.Text
+ }
+ end
+
+ return Button
+ ```
\ No newline at end of file
diff --git a/docs/tutorials/best-practices/instance-handling.md b/docs/tutorials/best-practices/instance-handling.md
new file mode 100644
index 000000000..b43722802
--- /dev/null
+++ b/docs/tutorials/best-practices/instance-handling.md
@@ -0,0 +1,187 @@
+Components are a good fit for Roblox instances. You can assemble complex groups
+of instances by combining simpler, self-contained parts.
+
+To ensure maximum compatibility, there are a few best practices to consider.
+
+-----
+
+## Returns
+
+Anything you return from a component should be supported by
+[`[Children]`](../roblox/parenting.md).
+
+```Lua
+-- returns an instance
+return scope:New "Frame" {}
+
+-- returns an array of instances
+return {
+ scope:New "Frame" {},
+ scope:New "Frame" {},
+ scope:New "Frame" {}
+}
+
+-- returns a state object containing instances
+return scope:ForValues({1, 2, 3}, function(use, scope, number)
+ return scope:New "Frame" {}
+end)
+
+-- mix of arrays, instances and state objects
+return {
+ scope:New "Frame" {},
+ {
+ scope:New "Frame" {},
+ scope:ForValues( ... )
+ }
+ scope:ForValues( ... )
+}
+```
+
+!!! fail "Returning multiple values is fragile"
+ Don't return multiple values directly from your function. When a function
+ returns multiple values directly, the extra returned values can easily get
+ lost.
+
+ ```Lua
+ local function BadThing(scope, props)
+ -- returns *multiple* instances (not surrounded by curly braces!)
+ return
+ scope:New "Frame" {},
+ scope:New "Frame" {},
+ scope:New "Frame" {}
+ end
+
+ local things = {
+ -- Luau doesn't let you add multiple returns to a list like this.
+ -- Only the first Frame will be added.
+ scope:BadThing {},
+ scope:New "TextButton" {}
+ }
+ print(things) --> { Frame, TextButton }
+ ```
+
+ Instead, you should return them inside of an array. Because the array is a
+ single return value, it won't get lost.
+
+If your returns are compatible with `[Children]` like above, you can insert a
+component anywhere you'd normally insert an instance.
+
+You can pass in one component on its own...
+
+```Lua hl_lines="2-4"
+local ui = scope:New "ScreenGui" {
+ [Children] = scope:Button {
+ Text = "Hello, world!"
+ }
+}
+```
+
+...you can include components as part of an array..
+
+```Lua hl_lines="5-7 9-11"
+local ui = scope:New "ScreenGui" {
+ [Children] = {
+ scope:New "UIListLayout" {},
+
+ scope:Button {
+ Text = "Hello, world!"
+ },
+
+ scope:Button {
+ Text = "Hello, again!"
+ }
+ }
+}
+```
+
+...and you can return them from state objects, too.
+
+```Lua hl_lines="8-10"
+local stuff = {"Hello", "world", "from", "Fusion"}
+
+local ui = scope:New "ScreenGui" {
+ [Children] = {
+ scope:New "UIListLayout" {},
+
+ scope:ForValues(stuff, function(use, scope, text)
+ return scope:Button {
+ Text = text
+ }
+ end)
+ }
+}
+```
+
+-----
+
+## Containers
+
+Some components, for example pop-ups, might contain lots of different content:
+
+
+
+
+Ideally, you would be able to reuse the pop-up 'container', while placing your
+own content inside.
+
+
+
+
+The simplest way to do this is to pass instances through to `[Children]`. For
+example, if you accept a table of `props`, you can add a `[Children]` key:
+
+```Lua hl_lines="4 8"
+local function PopUp(
+ scope: Fusion.Scope,
+ props: {
+ [typeof(Children)]: Fusion.Children
+ }
+)
+ return scope:New "Frame" {
+ [Children] = props[Children]
+ }
+end
+```
+
+!!! tip "Accepting multiple instances"
+ If you have multiple 'slots' where you want to pass through instances, you
+ can make other properties and give them the `Fusion.Children` type.
+
+Later on, when a pop-up is created, instances can now be parented into that
+pop-up:
+
+```Lua
+scope:PopUp {
+ [Children] = {
+ scope:Label {
+ Text = "New item collected"
+ },
+ scope:ItemPreview {
+ Item = Items.BRICK
+ },
+ scope:Button {
+ Text = "Add to inventory"
+ }
+ }
+}
+```
+
+If you need to add other instances, you can still use arrays and state objects
+as normal. You can include instances you're given, in exactly the same way you
+would include any other instances.
+
+```Lua
+scope:New "Frame" {
+ -- ... some other properties ...
+
+ [Children] = {
+ -- the component provides some children here
+ scope:New "UICorner" {
+ CornerRadius = UDim.new(0, 8)
+ },
+
+ -- include children from outside the component here
+ props[Children]
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/tutorials/components/children/Popup-Exploded-Dark.svg b/docs/tutorials/best-practices/instance-handling/Popup-Exploded-Dark.svg
similarity index 100%
rename from docs/tutorials/components/children/Popup-Exploded-Dark.svg
rename to docs/tutorials/best-practices/instance-handling/Popup-Exploded-Dark.svg
diff --git a/docs/tutorials/components/children/Popup-Exploded-Light.svg b/docs/tutorials/best-practices/instance-handling/Popup-Exploded-Light.svg
similarity index 100%
rename from docs/tutorials/components/children/Popup-Exploded-Light.svg
rename to docs/tutorials/best-practices/instance-handling/Popup-Exploded-Light.svg
diff --git a/docs/tutorials/components/children/Popups-Dark.svg b/docs/tutorials/best-practices/instance-handling/Popups-Dark.svg
similarity index 100%
rename from docs/tutorials/components/children/Popups-Dark.svg
rename to docs/tutorials/best-practices/instance-handling/Popups-Dark.svg
diff --git a/docs/tutorials/components/children/Popups-Light.svg b/docs/tutorials/best-practices/instance-handling/Popups-Light.svg
similarity index 100%
rename from docs/tutorials/components/children/Popups-Light.svg
rename to docs/tutorials/best-practices/instance-handling/Popups-Light.svg
diff --git a/docs/tutorials/best-practices/sharing-values.md b/docs/tutorials/best-practices/sharing-values.md
new file mode 100644
index 000000000..f77ec6143
--- /dev/null
+++ b/docs/tutorials/best-practices/sharing-values.md
@@ -0,0 +1,293 @@
+Sometimes values are used in far-away parts of the codebase. For example, many
+UI elements might share theme colours for light and dark theme.
+
+-----
+
+## Globals
+
+Typically, values are shared by placing them in modules. These modules can be
+required from anywhere in the codebase, and their values can be imported into
+any code.
+
+Values shared in this way are known as *globals*.
+
+=== "Theme.luau"
+
+ ```Lua linenums="1"
+ local Theme = {}
+
+ Theme.colours = {
+ background = Color3.fromHex("FFFFFF"),
+ text = Color3.fromHex("222222"),
+ -- etc.
+ }
+
+ return Theme
+ ```
+
+=== "Somewhere else"
+
+ ```Lua linenums="1"
+ local Theme = require("path/to/Theme.luau")
+
+ local textColour = Theme.colours.text
+ print(textColour) --> 34, 34, 34
+ ```
+
+In particular, you can share state objects this way, and every part of the
+codebase will be able to see and interact with those state objects.
+
+=== "Theme.luau"
+
+ ```Lua linenums="1"
+ local Fusion = require("path/to/Fusion.luau")
+
+ local Theme = {}
+
+ Theme.colours = {
+ background = {
+ light = Color3.fromHex("FFFFFF"),
+ dark = Color3.fromHex("222222")
+ },
+ text = {
+ light = Color3.fromHex("FFFFFF"),
+ dark = Color3.fromHex("222222")
+ },
+ -- etc.
+ }
+
+ function Theme.init(
+ scope: Fusion.Scope
+ )
+ Theme.currentTheme = scope:Value("light")
+ end
+
+ return Theme
+ ```
+
+=== "Somewhere else"
+
+ ```Lua linenums="1"
+ local Fusion = require("path/to/Fusion.luau")
+ local scoped, peek = Fusion.scoped, Fusion.peek
+
+ local Theme = require("path/to/Theme.luau")
+
+ local function printTheme()
+ local theme = Theme.currentTheme
+ print(
+ peek(theme),
+ if typeof(theme) == "string" then "constant" else "state object"
+ )
+ end
+
+ local scope = scoped(Fusion)
+ Theme.init(scope)
+ printTheme() --> light state object
+
+ Theme.currentTheme:set("dark")
+ printTheme() --> dark state object
+ ```
+
+Globals are very straightforward to implement and can be useful, but they can
+quickly cause problems if not used carefully.
+
+### Hidden dependencies
+
+When you use a global inside a block of reusable code such as a component, you
+are making your code dependent on another code file without declaring it to the
+outside world.
+
+To some extent, this is entirely why using globals is desirable. While it's more
+'correct' to accept the `Theme` via the parameters of your function, it often
+means the `Theme` has to be passed down through multiple layers of functions.
+This is known as [prop drilling](https://kentcdodds.com/blog/prop-drilling) and
+is widely considered bad practice, because it clutters up unrelated code with
+parameters that are only passed through functions.
+
+To avoid prop drilling, globals are often used, which 'hides' the dependency on
+that external code file. You no longer have to pass it down through parameters.
+However, relying too heavily on these hidden dependencies can cause your code to
+behave in surprising, unintuitive ways, or it can obscure what functionality is
+available to developers using your code.
+
+### Hard-to-locate writes
+
+If you write into globals from deep inside your code base, it becomes very hard
+to figure out where the global is being changed from, which significantly hurts
+debugging.
+
+Generally, it's best to treat globals as *read-only*. If you're writing to a
+global, it should be coming from a single well-signposted, easy-to-find place.
+
+You should also keep the principles of [top-down control](../callbacks) in mind;
+think of globals as 'flowing down' from the root of the program. Globals are
+best managed from high up in the program, because they have widespread effects,
+so consider using callbacks to pass control up the chain, rather than managing
+globals directly from every part of the code base.
+
+### Memory management
+
+In addition, globals can complicate memory management. Because every part of
+your code base can access them, you can't destroy globals until the very end of
+your program.
+
+In the above example, this is solved with an `init()` method which passes the
+main scope to `Theme`. Because `init()` is called before anything else that uses
+`Theme`, the objects that `Theme` creates will be added to the scope first.
+
+When the main scope is cleaned up, `doCleanup()` will destroy things in reverse
+order. This means the `Theme` objects will be cleaned up last, after everything
+else in the program has been cleaned up.
+
+This only works if you know that the main script is the only entry point in your
+program. If you have two scripts running concurrently which try to `init()` the
+`Theme` module, they will overwrite each other.
+
+### Non-replaceable for testing
+
+When your code uses a global, you're hard-coding a connection between your code
+and that specific global.
+
+This is problematic for testing; unless you're using an advanced testing
+framework with code injection, it's pretty much impossible to separate your code
+from that global code, which makes it impossible to replace global values for
+testing purposes.
+
+For example, if you wanted to write automated tests that verify light theme and
+dark theme are correctly applied throughout your UI, you can't replace any
+values stored in `Theme`.
+
+You might be able to write to the `Theme` by going through the normal process,
+but this fundamentally limits how you can test. For example, you couldn't run a
+test for light theme and dark theme at the same time.
+
+-----
+
+## Contextuals
+
+The main drawback of globals is that they hold one value for all code. To solve
+this, Fusion introduces *contextual values*, which can be temporarily changed
+for the duration of a code block.
+
+To create a contextual, call the `Contextual` function from Fusion. It asks for
+a default value.
+
+```Lua
+local myContextual = Contextual("foo")
+```
+
+At any time, you can query its current value using the `:now()` method.
+
+```Lua
+local myContextual = Contextual("foo")
+print(myContextual:now()) --> foo
+```
+
+You can override the value for a limited span of time using `:is():during()`.
+Pass the temporary value to `:is()`, and pass a callback to `:during()`.
+
+While the callback is running, the contextual will adopt the temporary value.
+
+```Lua
+local myContextual = Contextual("foo")
+print(myContextual:now()) --> foo
+
+myContextual:is("bar"):during(function()
+ print(myContextual:now()) --> bar
+end)
+
+print(myContextual:now()) --> foo
+```
+
+By storing widely-used values inside contextuals, you can isolate different
+code paths from each other, while retaining the easy, hidden referencing that
+globals offer. This makes testing and memory management significantly easier,
+and helps you locate which code is modifying any shared values.
+
+To demonstrate, the `Theme` example can be rewritten to use contextuals.
+
+=== "Theme.luau"
+
+ ```Lua linenums="1"
+ local Fusion = require("path/to/Fusion.luau")
+ local Contextual = Fusion.Contextual
+
+ local Theme = {}
+
+ Theme.colours = {
+ background = {
+ light = Color3.fromHex("FFFFFF"),
+ dark = Color3.fromHex("222222")
+ },
+ text = {
+ light = Color3.fromHex("FFFFFF"),
+ dark = Color3.fromHex("222222")
+ },
+ -- etc.
+ }
+
+ Theme.currentTheme = Contextual("light")
+
+ return Theme
+ ```
+
+=== "Somewhere else"
+
+ ```Lua linenums="1"
+ local Fusion = require("path/to/Fusion.luau")
+ local scoped, peek = Fusion.scoped, Fusion.peek
+
+ local Theme = require("path/to/Theme.luau")
+
+ local function printTheme()
+ local theme = Theme.currentTheme:now()
+ print(
+ peek(theme),
+ if typeof(theme) == "string" then "constant" else "state object"
+ )
+ end
+
+ printTheme() --> light constant
+
+ local scope = scoped(Fusion)
+ local override = scope:Value("light")
+ Theme.currentTheme:is(override):during(function()
+ printTheme() --> light state object
+ override:set("dark")
+ printTheme() --> dark state object
+ end)
+
+ printTheme() --> light constant
+ ```
+
+In this rewritten example, `Theme` no longer requires an `init()` function,
+because - instead of defining a state object globally - `Theme` only defines
+`"light"` as the default value.
+
+You're expected to replace the default value with a state object when you want
+to make the theme dynamic. This has a number of benefits:
+
+- Because the override is time-limited to one span of your code, you can have
+multiple scripts running at the same time with completely different overrides.
+
+- It also explicitly places your code in charge of memory management, because
+you're creating the object yourself.
+
+- It's easy to locate where changes are coming from, because you can look for
+the nearest `:is():during()` call. Optionally, you could share a limited,
+read-only version of the value, while retaining private access to write to the
+value wherever you're overriding the contextual from.
+
+- Testing becomes much simpler; you can override the contextual for different
+parts of your testing, without ever having to inject code, and without altering
+how you read and override the contextual in your production code.
+
+It's still possible to run into issues with contextuals, though.
+
+- You're still hiding a dependency of your code, which can still lead to
+confusion and obscuring available features, just the same as globals.
+- Unlike globals, contextuals are time-limited. If you connect to an event or
+start a delayed task, you won't be able to access the value anymore. Instead,
+capture the value at the start of the code block, so you can use it in delayed
+tasks.
\ No newline at end of file
diff --git a/docs/tutorials/best-practices/state.md b/docs/tutorials/best-practices/state.md
new file mode 100644
index 000000000..694dee4d3
--- /dev/null
+++ b/docs/tutorials/best-practices/state.md
@@ -0,0 +1,215 @@
+Components can hold their own data privately using state objects. This can be
+useful, but you should be careful when adding state.
+
+-----
+
+## Creation
+
+You can create state objects inside components as you would anywhere else.
+
+```Lua hl_lines="10 13-15"
+local HOVER_COLOUR = Color3.new(0.5, 0.75, 1)
+local REST_COLOUR = Color3.new(0.25, 0.5, 1)
+
+local function Button(
+ scope: Fusion.Scope,
+ props: {
+ -- ... some properties ...
+ }
+)
+ local isHovering = scope:Value(false)
+
+ return scope:New "TextButton" {
+ BackgroundColor3 = scope:Computed(function(use)
+ return if use(isHovering) then HOVER_COLOUR else REST_COLOUR
+ end),
+
+ -- ... ... some more code ...
+ }
+end
+```
+
+Because these state objects are made with the same `scope` as the rest of the
+component, they're destroyed alongside the rest of the component.
+
+-----
+
+## Top-Down Control
+
+Remember that Fusion mainly works with a top-down flow of control. It's a good
+idea to keep that in mind when adding state to components.
+
+When you're making reusable components, it's more flexible if your component can
+be controlled externally. Components that control themselves entirely are hard
+to use and customise.
+
+Consider the example of a check box. Each check box often reflects a state
+object under the hood:
+
+
+
+
+It might *seem* logical to store the state object inside the check box, but
+this causes a few problems:
+
+- because the state is hidden, it's awkward to read and write from outside
+- often, the user already has a state object representing the same setting, so
+now there's two state objects where one would have sufficed
+
+```Lua hl_lines="7"
+local function CheckBox(
+ scope: Fusion.Scope
+
-
-
+
{% endblock %}
-{% block disqus %}{% endblock %}
\ No newline at end of file
+{% block disqus %}{% endblock %}
+
+{% block site_nav %}
+
+ {% if nav %}
+ {% if page.meta and page.meta.hide %}
+ {% set hidden = "hidden" if "navigation" in page.meta.hide %}
+ {% endif %}
+
+ {% endif %}
+{% endblock %}
\ No newline at end of file
diff --git a/docs/api-reference/errors/error-paste-box.js b/docs/assets/scripts/error-paste-box.js
similarity index 90%
rename from docs/api-reference/errors/error-paste-box.js
rename to docs/assets/scripts/error-paste-box.js
index 76487a5fd..d060d48b2 100644
--- a/docs/api-reference/errors/error-paste-box.js
+++ b/docs/assets/scripts/error-paste-box.js
@@ -48,6 +48,4 @@ try {
} catch(e) {
alert("Couldn't instantiate the error paste box - " + e);
-}
-
-const input = "[Fusion] Computed callback error: attempt to index nil with 'get' (ID: computedCallbackError) ---- Stack trace ---- Replica";
\ No newline at end of file
+}
\ No newline at end of file
diff --git a/docs/assets/theme/404.css b/docs/assets/theme/404.css
index 1e6a0d140..06b0931a4 100644
--- a/docs/assets/theme/404.css
+++ b/docs/assets/theme/404.css
@@ -1,13 +1,40 @@
-.fusion-404 h1 {
- display: flex;
- align-items: center;
- justify-content: left;
+#fusion-404 .graphic {
+ display: block;
+ width: 16rem;
+ max-width: 80vmin;
+ aspect-ratio: 1;
+ margin: 0 auto;
+ margin-bottom: 2rem;
+ background-size: contain;
+ background-position: center;
+ background-repeat: no-repeat;
+}
+
+[data-md-color-scheme="fusiondoc-light"] #fusion-404 .graphic {
+ background-image: url("../404-light.svg");
+}
+
+[data-md-color-scheme="fusiondoc-dark"] #fusion-404 .graphic {
+ background-image: url("../404-dark.svg");
+}
+
+#fusion-404 h1 {
+ text-align: center;
font-size: 2rem;
+ margin-top: 0;
margin-bottom: 1rem;
}
-.fusion-404 h1 img {
- width: 6rem;
- height: 6rem;
- margin-right: 2rem;
+#fusion-404 h2 {
+ text-align: center;
+ font-size: 1rem;
+ font-weight: 400;
+
+ margin-top: 0;
+ margin-bottom: 2rem;
}
+
+#fusion-404 .advice {
+ max-width: max-content;
+ margin: 0 auto;
+}
\ No newline at end of file
diff --git a/docs/assets/theme/api-reference.css b/docs/assets/theme/api-reference.css
index a1667c190..df32bd7f2 100644
--- a/docs/assets/theme/api-reference.css
+++ b/docs/assets/theme/api-reference.css
@@ -1,88 +1,91 @@
.fusiondoc-api-header {
display: flex;
- align-items: center;
- gap: 0.75rem;
+ align-items: baseline;
margin: 0 !important;
flex-wrap: wrap;
}
-.fusiondoc-api-header .headerlink {
- display: none;
+.fusiondoc-api-header .fusiondoc-api-icon {
+ margin-right: 0.5em;
}
.fusiondoc-api-header > * {
flex-shrink: 0;
}
-.fusiondoc-api-header .fusiondoc-api-name {
- margin-right: auto;
+.fusiondoc-api-type {
+ vertical-align: middle;
+ font-size: calc((0.5em + 1rem) / 2);
+ flex-shrink: 0;
+
+ margin-left: 0.5em;
+
+ font-family: var(--md-code-font-family);
+ font-weight: 400;
+}
+
+.fusiondoc-api-type:not(a){
+ opacity: 0.8;
}
-.fusiondoc-api-pills {
+.fusiondoc-api-breadcrumbs {
display: flex;
align-items: center;
- justify-content: flex-end;
- gap: 0.5em;
- flex-wrap: wrap;
- line-height: 1.5em;
-
- font-size: 0.75rem;
- margin-left: 0.5em;
- margin-bottom: -2em;
+ height: 2rem;
+}
- letter-spacing: -0.02em;
- font-weight: 400;
- vertical-align: middle;
+.fusiondoc-api-breadcrumbs {
+ opacity: 0.8;
}
-.fusiondoc-api-pills + h1,
-.fusiondoc-api-pills + h2,
-.fusiondoc-api-pills + h3,
-.fusiondoc-api-pills + h4 {
- margin-top: 0;
+.fusiondoc-api-breadcrumbs > *:not(:last-child)::after {
+ content: "›";
+ margin: 0 0.25rem;
}
-.fusiondoc-api-header .fusiondoc-api-pills {
- font-size: 0.5em;
- margin-bottom: 0em;
+.fusiondoc-error-api-section {
+ opacity: 1;
+ transition: opacity 0.4s ease, filter 0.4s ease;
}
-.fusiondoc-api-pills > * {
- padding: 0.25em 0.75em;
- border-radius: 0.25rem;
- height: 2em;
- flex-shrink: 0;
+.fusiondoc-error-api-section.fusiondoc-error-api-section-defocus {
+ opacity: 0.4;
+ filter: blur(0.25rem);
+ pointer-events: none;
}
-.fusiondoc-api-pills .fusiondoc-api-pill-type {
- background-color: var(--fusiondoc-orange-a20);
- color: var(--fusiondoc-accent-text);
+.fusiondoc-api-bento {
+ column-width: 12rem;
+ column-gap: 0.5rem;
}
-.fusiondoc-api-pills .fusiondoc-api-pill-since {
- background-color: var(--fusiondoc-grey-a20);
- color: var(--fusiondoc-fg-1);
+.fusiondoc-api-bento > * {
+ break-inside: avoid;
+ background-color: var(--fusiondoc-bg-2);
+ box-shadow: var(--md-shadow-z1);
+ border-radius: 0.25rem;
+ padding: 0.75rem 1rem;
+ padding-bottom: 0.01rem;
+ margin: 0.5rem 0;
+ margin-top: 0;
}
-.fusiondoc-api-breadcrumbs {
- display: flex;
- align-items: center;
- height: 2rem;
+.fusiondoc-api-bento > * :first-child {
+ margin-top: 0 !important;
}
-.fusiondoc-api-breadcrumbs > a {
+.fusiondoc-api-bento > * > h3 {
+ font-size: 0.7rem;
color: var(--fusiondoc-fg-3);
+ font-weight: 700;
}
-.fusiondoc-api-breadcrumbs > a:hover {
- color: var(--fusiondoc-accent-hover);
+.fusiondoc-api-index-header {
+ color: var(--fusiondoc-fg-1) !important;
}
-.fusiondoc-api-breadcrumbs > a::after {
- content: "/";
- margin: 0 0.25rem;
- opacity: 0.5;
- color: var(--fusiondoc-fg-3);
+.fusiondoc-api-index-header:hover {
+ color: var(--fusiondoc-accent-hover) !important;
}
.fusiondoc-api-index-link {
@@ -99,20 +102,11 @@
}
.fusiondoc-api-index-link > .fusiondoc-api-index-arrow {
+ margin-bottom: -0.3em;
transform: translateX(0rem);
transition: transform 0.2s ease;
}
.fusiondoc-api-index-link:hover > .fusiondoc-api-index-arrow {
transform: translateX(0.5rem);
-}
-
-.fusiondoc-error-api-section {
- opacity: 1;
- transition: opacity 0.4s ease;
-}
-
-.fusiondoc-error-api-section.fusiondoc-error-api-section-defocus {
- opacity: 0.4;
- transition: opacity 0.4s ease;
}
\ No newline at end of file
diff --git a/docs/assets/theme/home.css b/docs/assets/theme/home.css
index 6eb6dc615..8b38869f6 100644
--- a/docs/assets/theme/home.css
+++ b/docs/assets/theme/home.css
@@ -41,6 +41,17 @@
background-repeat: no-repeat;
background-size: 177vh 100vh;
background-position: center right;
+ animation: home-fade-in-bg 0.5s ease 0.5s;
+ animation-fill-mode: forwards;
+}
+
+@keyframes home-fade-in-bg {
+ 0% {
+ transform: translateY(-0.8rem);
+ }
+ 100% {
+ transform: translateY(0rem);
+ }
}
[data-md-color-scheme="fusiondoc-dark"] #fusiondoc-home-main::before {
diff --git a/docs/assets/theme/page.css b/docs/assets/theme/page.css
index 0659e02f3..703bd121c 100644
--- a/docs/assets/theme/page.css
+++ b/docs/assets/theme/page.css
@@ -169,6 +169,10 @@
margin-right: 0rem;
}
+.md-header__title .md-header__topic:first-child {
+ height: 2.4rem;
+}
+
.md-header__title .md-header__topic:first-child::before {
content: "";
display: inline-block;
@@ -238,7 +242,7 @@
}
.md-copyright::after {
- content: "∙ Theme by Elttob";
+ content: "∙ Theme by Daniel P H Fox";
}
@media screen and (max-width: 76.1875em) {
diff --git a/docs/assets/theme/paragraph.css b/docs/assets/theme/paragraph.css
index a853eab0e..a3937e819 100644
--- a/docs/assets/theme/paragraph.css
+++ b/docs/assets/theme/paragraph.css
@@ -86,13 +86,4 @@ h6 > .twemoji:first-child {
font-style: normal;
font-size: 0.8em;
letter-spacing: 0.02em;
-}
-
-.fusiondoc-index-multicol {
- column-width: 15em;
-}
-
-.fusiondoc-index-multicol .fusiondoc-index-multicol-section {
- break-inside: avoid;
- padding-top: 0.001em; /* prevent margins collapsing */
}
\ No newline at end of file
diff --git a/docs/examples/cookbook/animated-computed.md b/docs/examples/cookbook/animated-computed.md
index a460dadf6..414a5403e 100644
--- a/docs/examples/cookbook/animated-computed.md
+++ b/docs/examples/cookbook/animated-computed.md
@@ -1,43 +1,114 @@
+This example shows you how to animate a single value with an animation curve of
+your preference.
+
+For demonstration, the example uses Roblox API members.
+
+-----
+
+## Overview
+
```Lua linenums="1"
--- [Fusion imports omitted for clarity]
+local Players = game:GetService("Players")
--- Oftentimes we calculate values for a single purpose, such as the position of
--- a single UI element. These values are often calculated inline, like this:
+local Fusion = -- initialise Fusion here however you please!
+local scoped = Fusion.scoped
+local Children = Fusion.Children
-local menuBar = New "Frame" {
- AnchorPoint = Computed(function(use)
- return if use(menuIsOpen) then Vector2.new(0.5, 0) else Vector2.new(0.5, -1)
- end)
-}
+local TWEEN_INFO = TweenInfo.new(
+ 0.5,
+ Enum.EasingStyle.Sine,
+ Enum.EasingDirection.InOut
+)
--- If you want to animate these inline values, you can pass them through an
--- object such as Spring and Tween- you don't have to do it separately.
+-- Don't forget to pass this to `doCleanup` if you disable the script.
+local scope = scoped(Fusion)
-local menuBar = New "Frame" {
- -- Use tweens for highly controllable animations:
- AnchorPoint = Tween(Computed(function(use)
- return if use(menuIsOpen) then Vector2.new(0.5, 0) else Vector2.new(0.5, -1)
- end), TweenInfo.new(0.2, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut)),
+-- You can set this at any time to indicate where The Thing should be.
+local showTheThing = scope:Value(false)
- -- Or use springs for more natural and responsive movement:
- AnchorPoint = Spring(Computed(function(use)
- return if use(menuIsOpen) then Vector2.new(0.5, 0) else Vector2.new(0.5, -1)
- end), 20, 0.5)
-}
+local exampleUI = scope:New "ScreenGui" {
+ Parent = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui"),
+ Name = "Example UI",
--- The equivalent 'expanded' code looks like this:
+ [Children] = scope:New "Frame" {
+ Name = "The Thing",
+ Position = scope:Tween(
+ scope:Computed(function(use)
+ local CENTRE = UDim2.fromScale(0.5, 0.5)
+ local OFFSCREEN = UDim2.fromScale(-0.5, 0.5)
+ return if use(showTheThing) then CENTRE else OFFSCREEN
+ end),
+ TWEEN_INFO
+ ),
+ Size = UDim2.fromOffset(200, 200)
+ }
+}
-local anchorPoint = Computed(function(use)
- return if use(menuIsOpen) then Vector2.new(0.5, 0) else Vector2.new(0.5, -1)
+-- Without toggling the value, you won't see it animate.
+task.defer(function()
+ while true do
+ task.wait(1)
+ showTheThing:set(not peek(showTheThing))
+ end
end)
+```
-local smoothAnchorPoint = Spring(anchorPoint, 20, 0.5) -- or equivalent Tween
+-----
-local menuBar = New "Frame" {
- AnchorPoint = smoothAnchorPoint
-}
+## Explanation
+
+There's three key components to the above code snippet.
+
+Firstly, there's `showTheThing`. When this is `true`, The Thing should be in
+the centre of the screen. Otherwise, The Thing should be off-screen.
+
+```Lua linenums="13"
+-- You can set this at any time to indicate where The Thing should be.
+local showTheThing = scope:Value(false)
+```
+
+Next, there's the computed object on line 26. This takes that boolean value, and
+turns it into a UDim2 position for The Thing to use. You can imagine this as the
+'non-animated' version of what you want The Thing to do, if it were to instantly
+teleport around.
+
+```Lua linenums="26"
+ scope:Computed(function(use)
+ local CENTRE = UDim2.fromScale(0.5, 0.5)
+ local OFFSCREEN = UDim2.fromScale(-0.5, 0.5)
+ return if use(showTheThing) then CENTRE else OFFSCREEN
+ end),
+```
+
+Finally, there's the tween object that the computed is being passed into. The
+tween object will smoothly move towards the computed over time. If needed, you
+could separate the computed into a dedicated variable to access it
+independently.
+
+```Lua linenums="25"
+ Position = scope:Tween(
+ scope:Computed(function(use)
+ local CENTRE = UDim2.fromScale(0.5, 0.5)
+ local OFFSCREEN = UDim2.fromScale(-0.5, 0.5)
+ return if use(showTheThing) then CENTRE else OFFSCREEN
+ end),
+ TWEEN_INFO
+ ),
+```
+
+The 'shape' of the animation is saved in a `TWEEN_INFO` constant defined earlier
+in the code. [The Tween tutorial](../../../tutorials/animation/tweens) explains
+how each parameter shapes the motion.
+
+```Lua linenums="7"
+local TWEEN_INFO = TweenInfo.new(
+ 0.5,
+ Enum.EasingStyle.Sine,
+ Enum.EasingDirection.InOut
+)
+```
--- Keep in mind that you probably shouldn't use inline animation for everything.
--- Sometimes you need to use the expanded form, or the expanded form would be
--- more efficient, and that's okay - choose what works best for your code :)
-```
\ No newline at end of file
+!!! tip "Fluid animations with springs"
+ For extra smooth animation shapes that preserve velocity, consider trying
+ [spring objects](../../../tutorials/animation/springs). They're very similar
+ in usage and can help improve the responsiveness of the motion.
\ No newline at end of file
diff --git a/docs/examples/cookbook/button-component.md b/docs/examples/cookbook/button-component.md
index 848222743..942315266 100644
--- a/docs/examples/cookbook/button-component.md
+++ b/docs/examples/cookbook/button-component.md
@@ -1,116 +1,180 @@
+This example is a relatively complete button component implemented using
+Fusion's Roblox API. It handles many common interactions such as hovering and
+clicking.
+
+This should be a generally useful template for assembling components of your
+own. For further ideas and best practices for building components, see
+[the Components tutorial](../../../tutorials/components/components).
+
+
+-----
+
+## Overview
+
```Lua linenums="1"
--- [Fusion imports omitted for clarity]
-
--- This is a relatively complete example of a button component.
--- It handles many common interactions such as hovering and clicking.
-
--- This should be a generally useful template for assembling components of your
--- own. Unless you're prototyping, it's probably wise to stick to some good
--- guidelines; the Tutorials have some tips if you don't have any existing
--- guidelines of your own.
-
--- Defining the names of properties the button accepts, and their types. This is
--- useful for autocomplete and helps catch some typos, but is optional.
-export type Props = {
- -- some generic properties we'll allow other code to control directly
- Name: CanBeState
- 
- 404
+ Oh noes!
- +
We couldn't find that page - it might have been moved or deleted. - -
- Here's some ideas on how to find it: -
-
-
- - Make sure there's no typos in the URL. - -
- - Use the search box above to try and find the page. - -
- - The page might not exist yet! - -
+ Here's some ideas on how to find it: +
-
+
- + Make sure there's no typos in the URL. + +
- + Use the search box above to try and find the page. + +
- + The page might not exist yet! + +