benvp/live_motion

High performance animation library for Phoenix LiveView

LiveMotion enables high performance animations declared on the server and run on the client.

Documentation

You can find the full API documentation on hexdocs.pm/live_motion.

Additionally you can find a few examples here: LiveMotion Examples.

Features

• Define animations declaratively directly in your HEEX templates. No definition of CSS classes or keyframes required.
• Animate page transitions using mount/unmount animations. See a little example at benvp.co. It's very subtle, but when you navigate, you see the page transitions.
• Trigger animations directly on the client using LiveMotion.JS (e.g. button clicks).

Installation

LiveMotion makes use of Phoenix LiveView hooks and therefore the setup requires a few more steps than just adding the dependency to the Mixfile. However, the JS part is included and works without node installed.

Add the live_motion dependency to your mix.exs file.

def deps do
  [
    {:live_motion, "~> 0.3"}
  ]
end

Open up your app.js and import createLiveMotion and initialize LiveMotion.

import { createLiveMotion } from 'live_motion';

const { hook: motionHook, handleMotionUpdates } = createLiveMotion();

Now in your hook definition, add the LiveMotion hook.

const hooks = {
  // your other hooks
  // ...
  ...motionHook,
};

Finally, we need to make sure that LiveView does not overwrite the style attributes generated by LiveMotion. In your LiveSocket initialization, add the following function into onBeforeElUpdated(from, to).

let liveSocket = new LiveSocket('/live', Socket, {
  params: { _csrf_token: csrfToken },
  hooks,
  dom: {
    onBeforeElUpdated(from, to) {
      // add this line
      handleMotionUpdates(from, to);
    },
  },
});

If you are using node and have npm or yarn installed, one additional step is required.

Show Instructions for npm / yarn

We need to add the JS part as a dependency to our package.json file. Add this to your package.json file.

{
  "dependencies": {
    "live_motion": "file:../deps/live_motion"
  }
}

Don't forget to run npm install or yarn afterwards.

Roadmap

There are still a lot of things to do to get to a mature library.

• Add tests
• Improve documentation
• See the limitations section.

Limitations

LiveMotion is still in the early days, so breaking changes are expected. Additionally, there are still a few limitations, which will be added in future releases.

• LiveMotion.motion always renders as a div element. Rendering any HTML element will be supported when LiveView 0.18.0 is ready.
• Due to the nature of spring animations, they do not have a fixed duration (theoretically they can run indefinetely). When using unmount transition, this adds a challenge, as we do not know how long Phoenix LiveView should defer the actual removal of the DOM node. For now, we fall back to the maximum supported duration of ten seconds.
• Layout animations are not yet supported. Think of animations which automatically move items in the correct place after an element is removed which affects the layout.

Contributing

Any contribution is very much welcome. The project itself works just as any other mix project.

Please do not include an updated priv/static/live_motion.js in pull requests. The maintainers will update it as part of the release process.

live_motion's Issues

Update for Phoenix 1.7

I tried using live motion on phoenix 1.7 and there was compatibility issues, so I forked the repo and updated phoenix. It worked.

Will this repo be updated for new phoenix?

How to trigger exit animation without LiveMotion.JS call

Hi!

Sorry for the barrage of issues, but I was wondering if there is a way to trigger the exit animation of a component via toggling a prop on the LiveMotion.motion component?

The docs outline a way to do trigger exit animations via a LiveMotion.JS call, but I can't seem to find a prop that will allow me trigger the exit animation by toggling the value of a prop.

Looking for something along the lines of:

            <LiveMotion.motion
              id="foo"
              show={@some_state_on_my_socket}
              animate={[y: 20, opacity: [0, 1]]}
              exit={[y: 0, opacity: [1, 0]]}
              transition={[duration: 1.5]}
            >

where toggling @some_state_on_my_socket to true or false would trigger the animate and exit animations respectively.

Is this supported? Thanks!

Next steps for presence

I want to collaborate with the presence branch. I want to use this for page transitions, and I love what I see on the Elixir forum.

Passing class via opts to `LiveMotion.motion` component

Hey again!

I was wondering if it was possible to style the wrapper div rendered by the LiveMotion.motion component via class selectors. The example below isn't working but I was imagining something like this:

<LiveMotion.motion 
    class="absolute w-full z-10" 
    ...
/>

Or a solution to be more generic than just supporting class:

<LiveMotion.motion 
    opts={[class: "absolute w-full z-10", "some-other-attribute": "some-attribute-value"]} 
    ...
/>

Adding to project, README instructions

I'm having trouble following the README to add this to a project.

Example:

import { createLiveMotion } from 'live_motion';
const { hook: motionHook, handleMotionUpdates } = createLiveMotion();

let Hooks = Object.assign({},
  SortableOption.hooks,
  Scrolling.hooks,
  AudioMp3.hooks,
  ...motionHook,
)

Errors on page load with JS console error: "Uncaught TypeError: Found non-callable @@iterator"

When I try expressing it more like how I expect it to be, it works.

let Hooks = Object.assign({},
  SortableOption.hooks,
  Scrolling.hooks,
  AudioMp3.hooks,
  motionHook
)

Just a simple update to README.md?

[LiveMotion] Motion element not found. Did you forget to make your target a LiveMotion.motion component?

I have done the setup as instructed in the readme, but I am unable to test any of the examples provided, in my application. I am getting this error on the console:

[LiveMotion] Motion element not found. Did you forget to make your target a LiveMotion.motion component?

This is my code in the LiveView Component:
`
import LiveMotion, only: [motion: 1]

def render(assigns) do
~H"""

🍿

<button type="button" phx-click={LiveMotion.JS.hide(to: "#popcorn")}> Eat popcorn

""" end ` Here is my app.js ` // Live Motion Library import { createLiveMotion } from 'live_motion';

const { hook: motionHook, handleMotionUpdates } = createLiveMotion();

const Hooks = {_, _, motionHook};
`

[Question] Is there a way to hook into animation lifecycle events?

Hi,

First off, I love this effort to make animations easier in LiveView.

I wanted to ask if a feature to hook into animation lifecycle events is something that would be in scope of this library? I'm thinking an API that would look like the following:

  <LiveMotion.motion id="popcorn" on_animation_end="popcorn_animation_end" animate={[rotate: 360]}>
    <span>🍿</span>
  </LiveMotion.motion>

Then in your LiveView you can define an event handler for "popcorn_animation_end":

def handle_event("popcorn_animation_end", _params, socket) do 
  # LiveView code that removes the popcorn element
end

One challenge with this is probably going to be making it flexible to use from within live components, where you would need to specify phx-target={@myself} in the eex to get handle_event messages passed to your component.

Would be happy to try to contribute this change if you could point me in the right direction

Animation does not trigger

Elixir 1.14
Phoenix 1.7.2

Im following all the instructions from README but library does not seem to work correctly.
Im trying to use Popcorn share example and on first page render the animation is triggered but then no effect when clicking on button.
No JS console warnings nor in Elixir console.

How can I debug it ?

Support PhoenixHTML 4.0

Because your app depends on live_motion ~> 0.3.1 which depends on phoenix_html ~> 3.1, phoenix_html ~> 3.1 is required.
So, because your app depends on phoenix_html ~> 4.0, version solving failed.

Issue before socket connected

I've noticed that the animations I've implemented would flash like a regular div on static rendering, before the socket is connected. I solved this by interpolating invisible into class if socket is not connected. But I feel this is a hackish solution. I'm wondering is this normal and expected? Am I doing something wrong?

JS error on server-side updates

live_motion/priv/static/live_motion.js

Line 881 in d9f5616

this.animate();

When settings a server-side attribute such as rotate: @rotate, upon update the updated function is called and the js throws an error:
Uncaught TypeError: this.animate is not a function.

animate() does not exist. Changing animate() to maybeAnimate() seems to work.