material-motion

Material Motion

Material Motion is a library used by the Material Design team to prototype interactive experiences with gestures.

Status: Experimental

🚨 Material Motion has not been used in a production application at Google. It is unstable and unsupported. 🚨

Unexplored areas

• bundle size

  Material Motion has not been run through Closure Compiler. No attempts have been made to minify its file size.

  Operators are presently implemented using the mixin pattern, which may not minify well. We may migrate to a pipeable architecture, like RxJS's, in a future version.

• memory footprint

  Interactions are implemented by composing streams of user input to emit styles like transform and opacity. We have not yet explored when/how these streams should be freed for garbage collection.

Other likely changes

• modularization

  Material Motion is split into packages:

  • material-motion is a pure JavaScript library with no dependencies on the DOM or opinions about how the view layer is implemented.
  • material-motion-views-dom contains functions for working with the DOM, like getPointerEventStreamsFromElement and combineStyleStreams.

  The original idea was to vend different views adaptors for different frameworks (React, Angular, etc.), separate from the pure logic in the core library. JSS does a good job binding observables to CSS in a framework-agnostic way; therefore, views-dom is likely to be folded into material-motion in a future version.

• function signatures

  Material Motion uses the named argument pattern to make it easier to evolve APIs without making breaking changes. There is usually a positional shorthand. For instance, these are equivalent:

  openOffset$.addedBy({ value$: thresholdAmount$ })  // named argument
  
  openOffset$.addedBy(thresholdAmount$)              // positional shorthand
  
  openOffset$.addedBy({                              // named argument, with
    value$: thresholdAmount$,                        // an explicit value for
    onlyEmitWithUpstream: false,                     // an optional parameter
  })
  

  All arguments that accept stream values are suffixed with $.

  The Material Motion API is declarative. Its operators accept literal values and other streams, but not functions. This decision was made to ensure the API is portable across platforms, and to provide a foundation for visual tooling to be built on top of.

  We will continue to assess the impact of these patterns on both ergonomics and code size, and may make changes in the future accordingly.

Usage

Material Motion is often used to implement the toss gesture: where the user drags an element, and when it's released, it springs to a resting position. Tossable observes the drag's velocity and passes it to the spring, preserving the user's momentum and making the interaction feel seamless.

Here's a simple example:

// We use JSS to update the document's style sheet whenever Material Motion
// emits a new value.
import { create as createJSS } from 'jss';
import createDefaultJSSPreset from 'jss-preset-default';

import {
  Draggable,
  Point2DSpring,
  Tossable,
} from 'material-motion';

import {
  combineStyleStreams,
  getPointerEventStreamsFromElement,
} from 'material-motion-views-dom';

// We're presuming there's an element on the page called "ball" that we want to
// make tossable.
const ball = document.getElementById('ball');

// `Draggable` listens for events on the down, move, and up streams.  It
// calculates how far a pointer has been dragged, and emits the result on its
// `value$` stream.
const pointerEvents = getPointerEventStreamsFromElement(ball);
const draggable = new Draggable(pointerEvents);

// `Tossable` passes the velocity from `draggable` into the spring.  This
// ensures that when the user lets go, the item continues moving at the same
// speed it was while the user was in control.
const spring = new Point2DSpring();
const tossable = new Tossable({ draggable, spring });

// `Tossable` outputs `translate$` and `willChange$`.
//
// `combineStyleStreams` will combine these into a stream of
// `{ transform, willChange }`, to be passed to JSS.
const ballStyles$ = combineStyleStreams(tossable.styleStreams);

// Unfortunately, there's a bit of boilerplate to instantiate JSS.  Notice
// that the output of `tossable` has been given the name `ball` here.
const styleSheet = jss.createStyleSheet(
  {
    ball: ballStyles$,
  },
  {
    link: true,
  }
).attach();

// Now, we assign the class name that JSS generated to the element that we
// received the pointer events from:
ball.classList.add(styleSheet.classes.ball);

You can see this in action at https://material-motion-demos.firebaseapp.com/toss/. The source code is in TossableDemo.

Documentation

Material Motion was originally a cross-platform initiative that targeted Android, iOS, and the Web. Although the other platforms are not currently in active development, you may find the documentation from the shared project helpful: https://material-motion.github.io/material-motion/documentation/

Unfortunately, there is not yet independent documentation for the JavaScript implementation. Hopefully, there will be in there future.

Installation

yarn add material-motion material-motion-views-dom

License

Apache 2.0