Animation API refactor #420

koenbok · 2016-09-17T19:26:05Z

Update: this now lives here: https://github.com/koenbok/Framer/wiki/New-Animation-API

Continuing from #378

API Overview

This is a current relevant overview of how the API will be from now on. For more information about what changed, see below.

`layer.animate(properties: object | state: string, options={})`

Returns: Animation object

properties or state: either an object with property values you want to animate to, or an existing state name.
options: options for the animation (see animationOptions).

This creates a new animation for a layer based on a state or new property values and starts it immediately. If the properties have an options key, it is used as options for the animation.

If there is currently an animation on the layer, it gets stopped if it is animating the same properties as the new animation. Simply put, no two animations can be ran on width at the same time, but you can have two separate animations, one running on width and the other on height.

Preferred Examples

Simple examples for animating of properties.

# Properties animation
layer.animate
    x: 200

# Properties spring animation
layer.animate
    x: 200
    options:
        curve: "spring"

Simple examples for animating with states.

layer.states.test =
    x: 200

# State animation
layer.animate "test"

# State animation with options
layer.animate "test",
    curve: "spring"

`layer.animateStop()`

Stop all animations for this layer.

`layer.animationOptions`

Animation objects manage animations that target a layer and properties. An animation will tween between a start and end value, with a curve. The start value is determined when the animation starts, and the end value is defined by properties. If the start values equal to end values, they won't animate.

curve — A string, set to ease by default. (Optional)
curveOptions — An object with the options of the set curve. (Optional)
time — A number, the duration in seconds. (Optional)
delay — A number, the delay of the animation. (Optional)
repeat — A number, the amount of times it repeats. (Optional)
colorModel — A string, the model to animate colors in. (Optional)
instant — A boolean, don't animate. (Optional)

`layer.states` (object)

The states object on a layer holds all the different states for a layer. They can be used to animate to, switch to, or cycled through. States are a great way to organize different visual properties of layers.

The properties of a state can be anything on a layer like x, y, etc. Properties that cannot be animated like html or visible can still be used but will not be animated. They will get set at the end of a transition.

States can have a special animationOptions key to hold animation options like curve. They will be used whenever layers get animated to that state.

There are two special states: current and previous. They refer to the current and last state that a layer is in. Additionally, the have a name key so you can check the current state name with layer.states.current.name.

Examples

# Set a single state
layer.states.stateA =
    x: 100

# Animate to the state  
layer.animate("stateA")

# Go to the state without animation
layer.stateSwitch("stateA")

Here is a common example where we set multiple states and cycle through them.

# Set multiple states at once
layer.states =
    stateA:
        x: 100
    stateB:
        x: 200

# On a click, go back and forth between states.
layer.onTap -> layer.stateCycle(["stateA", "stateB"])

`layer.statesCycle(states: array<string>?, options={})`

Changes overview

Animation

Change a property.

layer = new Layer


## After

layer.animate
  x: 100

## Before

layer.animate
  properties:
    x: 100

Change a property with options.

## Before

layer.animate
  properties:
    x: 100
  time: 0.5

## After

layer.animate
  x: 100
  options:
    time: 0.5

Change the animation curve.

## Before

layer.animate
  properties:
    x: 100
  curve: "spring(250, 50, 0)"

## After

layer.animate
  x: 100
  options:
    curve: "spring(250, 50, 0)"

States

Add a single state.

## Before

layer.states.add
  stateA:
    x: 100

## After

layer.states.stateA = 
  x: 100

Define multiple states at once.

## Before

layer.states.add
  stateB:
    x: 200
  stateC:
    x: 400

## After

layer.states =
  stateB:
    x: 200
  stateC:
    x: 400

Notice the subtle difference between calling a function and setting a property. This means that where previously it was possible to add multiple states multiple times, in the new API we will override the existing states when calling layer.states = ... again. However, this is really unlikely and one could still achieve this by doing:

layer.states =
  stateA:
    x: 100
  stateB:
    x: 200

layer.states = _.extend layer.states,
  stateC:
    x: 300
  stateD:
    x: 400

Animate to state.

## Before

layer.states.switch "stateA"

## After

layer.animate "stateA"

Animate to state with options.

## Before

layer.states.add
  stateE:
    x: 200

layer.states.switch "stateE",
  curve: "ease-in"

## After

layer.states.stateE =
    x: 200

layer.animate "stateE",
    curve: "ease-in"

States can now also include animation options in the state itself. This is handy for declaring how to animate to a state as well. This has the exact same result as above.

layer.states.stateE =
    x: 200
    animationOptions:
        curve: "ease-in"

layer.animate "stateE"

Instantly switch to a state

Switching instantly will become an option of the animation

## Before

layer.states.switchInstant "stateB"

## After

layer.stateSwitch "stateB"

## Which will be a shorthand for:

layer.animate "stateB",
    instant: true

This means it can also be defined directly in a state itself:

layer.states = 
   stateA:
     x: 100
     animationOptions:
         instant: true

Cycling through state

Next has been renamed to cycling, because next was pretty ambigious depending on the context.

## Before

layer.states.next()
layer.states.next("stateB","stateC")

## After

layer.stateCycle()
layer.stateCycle(["stateB", "stateC"])  # Preferred
layer.stateCycle("stateB", "stateC")    # Also valid

# With options
layer.stateCycle ["stateB", "stateC"],
    time: 0.5

Notice how we use an array of states names here, to support animation options as second argument

Special states

There are three special states that will be set automatically and can't be overridden:

layer.states.default - The state the layer had upon creation.
layer.states.previous - The previous state the layer was in
layer.states.current - The current state the layer is in

These states contain the actual values and not (as is the case with layer.states.current now) the state string. The name of the previous an current states will still be available through layer.states.previous.name and layer.states.current.name. The name key only gets added in the context of these special states, so the special state objects are not the same as the actual state object. They are completely equal, with the name key added.

Notice the absence of layer.states.next, this functionality will be provided by layer.stateCycle() as described above.

Listing all the states

We will add a new property layer.stateNames that lists all the names of states currently defined on a layer. This list will contain layer.states.initial, but won't contain default and current.

layer.states = 
    left:
        x: Align.left
    right:
        x: Align.right

layer.stateCycle()

print layer.states.current.name # "left"
print layer.stateNames # ["default", "left", "right"]

The states on a layer is pretty much a normal object. So you can use different ways to loop through the states.

layer.states = 
    left:
        x: Align.left
    right:
        x: Align.right

# All thsese print ["default", "left", "right"]
print layer.stateNames # ["default", "left", "right"]
print Object.keys(layer.states)
print _.keys(layer.states)
print (k for k of layer.states)

# But beware of this one, it is empty: []
print (k for k in layer.states)

Older stuff:

Some refactoring for the new animation api

Move state switching responsibility back to the LayerStateMachine.
Clean up animation events; AnimationStart, AnimationStop and AnimationEnd.
Deprecate StateWillSwitch and StateDidSwitch in favor of StateSwitchStart, StateSwitchStop and StateSwitchEnd.
Refactored LayerStates to use prototype properties, so we don't make them in constructor.

Changes

You cannot override the deprecated names anymore (like .add) to use as a state name, because they would not show up in state names.
Remove the initial state and keep default as is.

Worries

Ideally Object.keys(layer.states) should be the same as for k in layer.states but that does not seem to be possible.
Maybe we need to change layer.states.current back from the name to the actual properties and add a name if you return them so you can do layer.states.current.name. This would lose comparison by reference, though.
There is a (double) circular dependency between Layer → LayerStates → LayerStateMachine and back. Not the end of the world, but I'm not sure if the GC is happy about this.

See: https://github.com/motif/company/issues/2633, https://github.com/motif/company/issues/2635

- Made the methods on the prototype vs in constructor - Added back LayerStateMachine.reset()

koenbok · 2016-09-18T07:41:08Z

https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Object/keys

The Object.keys() method returns an array of a given object's own enumerable properties, in the same order as that provided by a for...in loop (the difference being that a for-in loop enumerates properties in the prototype chain as well).

Given this, I think we could actually make Object.keys and for...in work like expected.

koenbok · 2016-09-18T08:36:51Z

So, this begs the question; what should this do?

layer = new Layer

print "layer.stateNames", layer.stateNames
print "Object.keys", Object.keys(layer.states)
print "for..in", (k for k in layer.states)

The current output is:

» "layer.stateNames", ["default"]
» "Object.keys", []
» "for..in", []

To me, it seems like:

All three always need to be equal. [update: impossible, see below]
I'd prefer to lean towards ["initial"] and hide default, but maybe not when we use deprecated methods (so we don't break compatibility).

koenbok · 2016-09-18T11:07:08Z

All right, so we can't get for..in to behave exactly like Object.keys() which is sad. See the full lookup table of how they work here. But for..of works well, which is closest to what we can get.

I also have default replaced with initial except when you are using deprecated methods. The only breaking exception is when you listen to StateDidSwitch, the previous/current will always be initial, never default.

- We now always use initial, unless you are using deprecated methods. - .stateNames, Object.keys(layer.states) and for...of all work the same (except for for...in) - The initial state is managed by LayerStates again.

nvh · 2016-09-18T11:54:39Z

@koenbok about default/initial: have you seen: https://github.com/motif/company/issues/2624

koenbok · 2016-09-18T12:44:52Z

Yeah :-/ let's chat about it tomorrow.

koenbok · 2016-09-19T13:57:28Z

Ok, re: https://github.com/motif/company/issues/2624 we decided to rip out the initial state for now and keep default the way it is.

nvh

Think all's good, have some minor suggestions and questions. If you have some general remarks about this refactor, I'd also like to hear them!

nvh · 2016-09-19T14:23:03Z

framer/Animation.coffee

+		# Mix of current and old api
+		if arguments.length is 2
+			layer = args[0]
+			if args[1].properties


Shouldn't we check for null with
if args[1].properties?

nvh · 2016-09-19T14:24:26Z

framer/Animation.coffee

+				properties = args[1].properties
+			else
+				properties = args[1]
+			options = args[1].options if args[1].options


Same here args[i].options?

nvh · 2016-09-19T14:24:59Z

framer/Animation.coffee

+		delete options.properties
+		delete options.options
+
+		# print "Animation", layer, properties, options


This can be removed

nvh · 2016-09-19T14:26:05Z

framer/Animation.coffee

@@ -64,6 +96,9 @@ class exports.Animation extends BaseClass
 		@_originalState = @_currentState()
 		@_repeatCounter = @options.repeat

+	@define "layer",
+		get: -> @_layer


I use later setting of layers in the animation preview of autocode. Are you ok with just using private api there?

Yeah let's do that for now

nvh · 2016-09-19T14:28:03Z

framer/Extras/TouchEmulator.coffee

@@ -195,6 +195,7 @@ class TouchEmulator extends BaseClass
 				curve: "ease-out"

 	hideTouchCursor: ->
+		return unless @touchPointLayer.opacity > 0


Why is this in this PR?

nvh · 2016-09-19T14:35:28Z

framer/Layer.coffee

-		#Support the old properties syntax
-		if properties.properties?
-			# console.warn "Using Layer.animate with 'properties' key is deprecated: please provide properties directly and use the 'options' key to provide animation options instead"
+		# print "layer.animate", properties, options


Print comment can be removed

nvh · 2016-09-19T14:36:18Z

framer/Layer.coffee

+
+		# Support the old properties syntax, we add all properties top level and
+		# move the options into an options property.
+		if properties.hasOwnProperty("properties")


Why do we check hasOwnProperty here instead of doing properties.properties?

nvh · 2016-09-19T14:37:49Z

framer/Layer.coffee

+		# With the new api we treat the properties as animatable properties, and use
+		# the special options keyword for animation options.
+		if properties.hasOwnProperty("options")
+			options = _.defaults(properties.options, options)


I think specifying options in the function should have precedence over specifying them in a options key

nvh · 2016-09-19T14:40:22Z

framer/Layer.coffee

-		get: -> @_stateMachine.states
+		get: ->
+			@_states ?= new LayerStates(@)
+			return @_states


I really dislike this behaviour of capturing the state inside of a getter, leads to unexpected behaviour. Can't we add it to the creation / addition of states?

Well, I'd like that, but:

There is no hook to see if a state gets created (because it's just an object key).

This guarantees backwards compat

Agree with 2), we could fix 1) if we ever move to initial, but am I correct that in order to drop this, we would also need to drop the backwards compatibility of default?

nvh · 2016-09-19T14:41:49Z

framer/Layer.coffee

-			for name, state of states
-				@_stateMachine.states[name] = state
+			@states.machine.reset()
+			_.extend(@states, states)


We could capture the current state of the layer here, we should however be aware of the setting of states individually...

Not really, because this should work too:

layer = new Layer layer.states.test = {x: 500} layer.animate "default"

nvh · 2016-09-19T14:44:58Z

test/tests/LayerStatesTest.coffee


 		it "should have an extra state", ->
 			layer = new Layer
 			layer.states.test = {x: 100}
-			testStates(layer, ["initial", "test"])
+			testStates(layer, ["default", "test"])


We could use initialStateName here as well

nvh

🏸

nvh

Again, some minor remarks, but noting really blocking

nvh · 2016-09-20T12:31:08Z

framer/Layer.coffee

-			return @animateToState(properties, options)
+			# Support options as an object
+			options = options.options if options.options?
+			return @states.machine.switchTo(properties, options)


It would be nicer to put properties in a new variable stateName here to make it more clear what is happening

nvh · 2016-09-20T12:31:36Z

framer/Layer.coffee

 		states = []
 		states = _.flatten(args) if args.length
 		@animate(@states.machine.next(states), options)

+	stateSwitch: (stateName, options={}) ->
+		@animate(stateName, _.defaults({}, options, {instant:true}))


Do we want to support animated: true?

nvh · 2016-09-20T12:32:37Z

framer/LayerStateMachine.coffee

@@ -21,7 +21,7 @@ class exports.LayerStateMachine extends BaseClass
 		get: -> @_currentName

 	@define "previousName",
-		get: -> _.last(@_previousNames)
+		get: -> _.last(@_previousNames) or "default"


Why do we need this? (I don't understand the case where _.last(@_previousNames) is null)

I think it's better to always return something here so you don't have to do a null check (if you just created a layer and ask for layer.states.previous.x.

nvh · 2016-09-20T12:33:24Z

framer/LayerStates.coffee

@@ -15,6 +15,9 @@ deprecatedWarning = (name, suggestion) ->
 	message += ", use '#{suggestion}' instead." if suggestion?
 	console.warn message

+namedState = (state, name) ->
+	return _.extend({}, state, {name: name})


Don't we want to enforce the named state by reversing state and {name: name}

nvh · 2016-09-20T12:34:50Z

test/tests/LayerStatesTest.coffee

@@ -3,6 +3,9 @@ assert = require "assert"

 initialStateName = "default"

+cleanState = (state) ->
+	return _.pickBy(state, (value, key) -> key isnt "name")


This could have a better name then cleanState, maybe removeKeysFromState(state,keys=["name"])?

nvh · 2016-09-20T12:35:59Z

test/tests/LayerStatesTest.coffee

@@ -158,24 +185,24 @@ describe "LayerStates", ->
 		# it "should be a no-op to change to the current state", ->
 		# 	layer = new Layer
 		# 	layer.states.stateA = {x: 100}
-		# 	layer.switchInstant "stateA"
+		# 	layer.stateSwitch "stateA"
 		# 	animation = layer.animate "stateA", time: 0.05
 		# 	assert.equal(animation, null)


Why is this test disabled?

Because the behaviour changed. We actually do always return an animation now so that the events get called and you can skip a null check.

Great. Then it can be removed instead of commented out

koenbok · 2016-09-20T13:46:47Z

Review @nvh?

nvh

LGTM

koenbok · 2016-09-21T11:49:31Z

Ok here we go.

koenbok added 5 commits September 16, 2016 21:06

Add some more unit tests

f6f49f1

Cleanup; enable all tests again

d1e2b23

Made LayerStateMachine depend on LayerStates

6b32cae

Move backward tests into their own file

80190f2

Refactored LayerStates

d70650e

- Made the methods on the prototype vs in constructor - Added back LayerStateMachine.reset()

Work on initial/default

0c02b31

- We now always use initial, unless you are using deprecated methods. - .stateNames, Object.keys(layer.states) and for...of all work the same (except for for...in) - The initial state is managed by LayerStates again.

koenbok added 3 commits September 19, 2016 16:10

Don't play the touch emulator animation all the time

db79bef

Make sure we don't modify the options directly

a19b1b4

Removed initial state

674c420

nvh requested changes Sep 19, 2016

View reviewed changes

nvh reviewed Sep 19, 2016

View reviewed changes

koenbok added 2 commits September 20, 2016 10:46

Experimental callbacks on animation / state options

1708166

Implement @nvh suggestions

f1af6bd

nvh approved these changes Sep 20, 2016

View reviewed changes

koenbok added 7 commits September 20, 2016 11:40

Support all layer.animate variations

9601a55

Implement layer.stateCycle

6f204e8

Add switch test

73b5332

Implement layer.stateSwitch

b59908e

Halfway implement layer.states.current.name

4573856

Remove _previousState

01947b5

Kill currentName

c430c6f

nvh approved these changes Sep 20, 2016

View reviewed changes

Test for stateCycle withou arguments

60f0ae8

nvh approved these changes Sep 20, 2016

View reviewed changes

koenbok added 2 commits September 21, 2016 13:26

Implement suggestions by @nvh

f1d41c3

Merge branch 'master' into animation-api-refactor

a76c862

koenbok changed the title ~~Animation api refactor~~ Animation API refactor Sep 21, 2016

koenbok merged commit 99f0882 into master Sep 21, 2016

bnbry mentioned this pull request Sep 25, 2016

Update readme and demo to use new animation api #427

Merged

nvh deleted the animation-api-refactor branch January 17, 2018 16:29

Animation API refactor #420

Animation API refactor #420

Conversation

koenbok commented Sep 17, 2016 • edited by nvh Loading

API Overview

layer.animate(properties: object | state: string, options={})

Returns: Animation object

Preferred Examples

layer.animateStop()

layer.animationOptions

layer.states (object)

Examples

layer.statesCycle(states: array<string>?, options={})

Changes overview

Animation

States

Instantly switch to a state

Cycling through state

Special states

Listing all the states

Older stuff:

Changes

Worries

koenbok commented Sep 18, 2016 • edited Loading

koenbok commented Sep 18, 2016 • edited Loading

koenbok commented Sep 18, 2016

nvh commented Sep 18, 2016

koenbok commented Sep 18, 2016

koenbok commented Sep 19, 2016

nvh left a comment

Choose a reason for hiding this comment

nvh Sep 19, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nvh Sep 19, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nvh Sep 19, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nvh left a comment

Choose a reason for hiding this comment

nvh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nvh Sep 20, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nvh Sep 20, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

koenbok commented Sep 20, 2016

nvh left a comment

Choose a reason for hiding this comment

koenbok commented Sep 21, 2016

koenbok commented Sep 17, 2016 •

edited by nvh

Loading

`layer.animate(properties: object | state: string, options={})`

`layer.animateStop()`

`layer.animationOptions`

`layer.states` (object)

`layer.statesCycle(states: array<string>?, options={})`

koenbok commented Sep 18, 2016 •

edited

Loading

koenbok commented Sep 18, 2016 •

edited

Loading

nvh Sep 19, 2016 •

edited

Loading

nvh Sep 19, 2016 •

edited

Loading

nvh Sep 19, 2016 •

edited

Loading

nvh Sep 20, 2016 •

edited

Loading

nvh Sep 20, 2016 •

edited

Loading