Addition of a declarative API alongside the currently imperative one

[Nidoxs]

ReactFlow does not currently support on-the-fly changing of spring goals declaratively (similar to RoactSpring, see the documentation relating to its declarative API here).

I think this would be a prudent addition to ReactFlow, as it helps cut down some of the imperative calls to update / start the animation when you just want the spring's goal to reflect React state. I think there's space for both a declarative and imperative API here. I also think this change would make sure ReactFlow respects the declarative nature of React, as currently this library is focused on the imperative from an end user perspective.

Current Version

This example works but is a little unnecessarily cluttered in my opinion:

local ReactFlow = require(game.ReplicatedStorage.Packages.ReactFlow)
local React = require(game.ReplicatedStorage.Packages.React)

local function MyComponent(props)
    local hovered = React.useState(false)

    local color, setColor = ReactFlow.useSpring({
        start = Color3.fromRGB(0,0,0),
        target = Color3.fromRGB(255,255,255)
    })

    -- if the color was based on the hovered state, you'd have to update it like so
    if hovered then
        setColor({
            target = Color3.fromRGB(255,255,255)
        })
    else
        setColor({
            target = Color3.fromRGB(150,150,150)
        })
    end

    -- or even this:
    setColor({
        target = if hovered then Color3.fromRGB(255,255,255) else Color3.fromRGB(150,150,150)
    })

    return e("TextButton", {
        BackgroundColor3 = color
    })
end

Proposed Version

Shorter and easier to read:

local ReactFlow = require(game.ReplicatedStorage.Packages.ReactFlow)
local React = require(game.ReplicatedStorage.Packages.React)

local function MyComponent(props)
    local hovered = React.useState(false)

    local color, setColor = ReactFlow.useSpring({
        start = Color3.fromRGB(0,0,0),
        target = if hovered then Color3.fromRGB(255,255,255) else Color3.fromRGB(150,150,150)
    })

    return e("TextButton", {
        BackgroundColor3 = color
    })
end

The imperative API should be retained as there are certainly use cases for it in my opinion. In my own experience, I've had to handle animations of React UI based on more than just a single React state (like hovered etc) so I think keeping what you've got so far is wise, this would be an addition on top of it to support on-the-fly updating of animation goals via the hook props tables. 😄

[Nidoxs]

I've not looked into ReactFlow's internals for enough time yet to suggest an ideal implementation for this, but I think given what I've seen so far it may be a case of having a useEffect in each hook that checks if the hook's props table has changed (so target, speed, damper etc.) and then it would call the controller.start function to propogate those updates.

One thing we'd want to avoid here is the start property being used again during that on-the-fly update otherwise you'll have the animation abruptly jumping to the starting state before moving to the new goal. I overcame that while experimenting by creating a third argument to the controller start function called ignoreStart which was then used to determine if the animation needed to jump to the start before playing to the new goal (which is required when it's the initial animation). I would point out that this got a little more involved with the useTween hook, so it may need a bit more thought.

Some further thought will be needed for how this new declarative API works with the GroupAnimation part of this library (certain animations within a group starting automatically, while others remain paused and need to be manually played).

Let me know what you think anyway! 😄

[GreenDeno]

Hi Nidoxs,

This is an interesting proposal, but I'm having troubling understanding how this will work in practice alongside the imperative APIs. Allowing spring goals to update arbitrarily introduces another source of truth: the hook config vs imperative controller calls. Which makes animation lifecycles harder to reason about.

In addition, springs are time-based and stateful, so semantically updating them via render props hides imperative behavior inside the hook. An event like hovered changing is inherently imperative, so using an explicit useEffect to respond to state changes keeps causality and timing clear.

I think a declarative API could work well and I'm open to ideas for keeping it predictable alongside the imperative hooks.

[Nidoxs]

Hey @GreenDeno!

Thanks for the response, I appreciate it! 😄

You raise a good point here and I think a good way to make the behaviour of these hooks more predictable (and less difficult to reason about internally) is to take some inspiration from how RoactSpring does it. There's definitely other ways to go about it, but RoactSpring achieves it like so:

Declarative

In the declarative mode / API a table is passed directly to the hook with the current goal for the spring, the hook then handles the updating of this goal if the props have changed. It's purely driven by React state and ternary operators. Helpful for more concise goal setting when you don't need the freedom of imperative calls.

local spring = ReactSpring.useSpring({
    color = if hovered then Color3.fromRGB(1,1,1) else Color3.fromRGB(0.75, 0.75, 0.75)
})

Imperative

In the imperative mode / API a function is passed directly to the hook that returns the current goal and then an API table which contains the methods to update or stop the spring etc. This grants you the freedom to imperatively update the spring and also chain onto it to scaffold several animations as per your requirements (similar concept to the "Chainable Animations" section of the ReactFlow README)

local spring, api = ReactSpring.useSpring(function()
    return {
        color = Color3.fromRGB(0.75, 0.75, 0.75) -- starts at the default color
        config = { --[[ config details here for the spring ]] }
    }
end)

-- later on when the button is hovered we call this imperatively
api.start({
    color = Color3.fromRGB(1,1,1)
})

-- chaining is possible here too (but only for the imperative mode)
api.start({
    color = Color3.fromRGB(1,1,1)
}):andThen(function()
    print("Animation complete")
end)

The Way Forward

We obviously don't need to mimick this 1:1, I just wanted to show what I'm used to currently to better communicate what I'd love to see implemented. We could also explore other avenues like an Imperative and Declarative sub-table of the library that contain separate hooks that manage the logic differently, although I feel this is a little "on the nose". A compromise could be retaining the hooks that exist now but internally branching off into either a useImperativeSpring or useDeclarativeSpring hook based on what's passed in, that way the end user doesn't have to worry about indexing the right part of the library and can just use a single hook.

Something like this:

local function useSpring(props)
    if typeof(props) == "table" then
        return useDeclarativeSpring(props)
    elseif typeof(props) == "function" then
        return useImperativeSpring(props)
    end
end

This way we essentially diverge the behaviour of the hook entirely based on the type of API the end user wants to work with, we don't have to worry about source of truth issues because in both cases they are clearly established:

• If you use declarative, your source of truth must always be driven by the table you pass into useSpring, you cannot update it imperatively.
• If you use imperative, your source of truth must always be driven by function calls that take a table of the new goal / values, you cannot update it on the fly like with declarative.

Then, the end user would pick the right API for their task given this knowledge (readme will need an update).

Testing

Just a final point on testing too, I noticed there's a Test file that handles creating the components for the story and animates them. We could rename that to ImperativeTest and create a new file called DeclarativeTest which does either similar animations to the imperative one but declaratively using the new API, or does different animations for the purposes of the declarative test.

[OutOfBears]

I love this approach, originally I was abit hesitant to changing the API because I always want to support backwards compatibility, but I think going forward I'm going to offer "function" versions of the API's that allows you to change the parameters of the spring during a render to allow a spring to re-target / re-tween. However I don't think this will be the case for group animations / sequences.