From 013e58fa68d3725e3e7cf246afa8605d7dc8243a Mon Sep 17 00:00:00 2001 From: lynnjepsen Date: Wed, 2 Aug 2017 10:42:07 -0700 Subject: [PATCH 1/3] docs(animation): Simplify README to follow best practices --- packages/mdc-animation/README.md | 103 ++++++++++++++----------------- 1 file changed, 48 insertions(+), 55 deletions(-) diff --git a/packages/mdc-animation/README.md b/packages/mdc-animation/README.md index 752fe99d77b..9f64089a9a6 100644 --- a/packages/mdc-animation/README.md +++ b/packages/mdc-animation/README.md @@ -9,7 +9,7 @@ path: /catalog/animation/ # Animation -MDC Animation is a Sass / CSS / JavaScript library which provides a toolbelt for Material Design animation, based off of the [motion guidelines](https://material.io/guidelines/motion/duration-easing.html#duration-easing-common-durations). Currently, it only covers easing curves. +Material in motion is responsive and natural. Use these easing curves and duration patterns to create smooth and consistent motion. ## Design & API Documentation @@ -27,59 +27,68 @@ npm install --save @material/animation ## Usage -We currently have variables for the following 4 animation curves: +### CSS Classes + +Some components have a set typographic style. For example, a raised MDC Checkbox enter and exit curves. + +If you want to animate an element, which is not a Material Design component, you can apply the following CSS classes. -| Variable name | timing function | use case | -| --- | --- | --- | -| `$mdc-animation-standard-curve-timing-function` | `cubic-bezier(.4, 0, .2, 1)` | Standard curve; any animations that are visible from start to finish (e.g. a FAB transforming into a toolbar) | -| `$mdc-animation-deceleration-curve-timing-function` | `cubic-bezier(0, 0, .2, 1)` | Animations that cause objects to enter the screen (e.g. a fade in) | -| `$mdc-animation-acceleration-curve-timing-function` | `cubic-bezier(.4, 0, 1, 1)` | Animations that cause objects to leave the screen permanently (e.g. a fade out) | -| `$mdc-animation-sharp-curve-timing-function` | `cubic-bezier(.4, 0, .6, 1)` | Animations that cause objects to leave the screen temporarily (e.g. closing a drawer) | +CSS Class | Description +--- | --- +`mdc-animation-deceleration-curve` | Sets the speed curve to deceleration +`mdc-animation-standard-curve` | Sets the speed curve to standard, a.k.a quickly accelerate and slowly decelerate +`mdc-animation-acceleration-curve` | Sets the speed curve to acceleration +`mdc-animation-sharp-curve` | Sets the speed curve to sharp, a.k.a quickly accelerate and decelerate -### SCSS +### Sass Variables and Mixins -Simply drop `mdc-animation` into your build and start using the variables: +Instead of setting CSS classes on elements, you can use the Sass mixins to achieve the same goal. ```scss -.mdc-thing--animating { - animation: foo 175ms $mdc-animation-standard-curve-timing-function; +.my-element--animating { + @include mdc-animation-acceleration-curve; } ``` -or the mixins, which simply assign their corresponding variables to the `animation-timing-function` -property: +Mixin | Description +--- | --- +`mdc-animation-deceleration-curve` | Sets the speed curve to deceleration +`mdc-animation-standard-curve` | Sets the speed curve to standard, a.k.a quickly accelerate and slowly decelerate +`mdc-animation-acceleration-curve` | Sets the speed curve to acceleration +`mdc-animation-sharp-curve` | Sets the speed curve to sharp, a.k.a quickly accelerate and decelerate + +We also provide the timing functions used by these mixins, which you can use with the `animation` or `transition` CSS properties ```scss -.mdc-thing--on-screen { - @include mdc-animation-acceleration-curve; +.my-element--animating { + animation: foo-keyframe 175ms $mdc-animation-standard-curve-timing-function; } ``` -Every mixin has the same name as its corresponding variable, without the `-timing-function` suffix. +Variable | Description +--- | --- +`mdc-animation-deceleration-curve-timing-function` | Timing function to decelerate +`mdc-animation-standard-curve-timing-function` | Timing function to quickly accelerate and slowly decelerate +`mdc-animation-acceleration-curve-timing-function` | Timing function to accelerate +`mdc-animation-sharp-curve-timing-function` | Timing function to quickly accelerate and decelerate -MDC Animation also provides helper functions for defining transitions for when something enters and exits the frame. A -very common example of this is something that fades in and then fades out using opacity. +The following functions create transitions given `$name` and the `$duration`. You can also specify `$delay`, but the default is 0ms. `$name` can either refer to the keyframe, or to CSS property used in `transition`. ```scss -@import "@material/animation/functions"; - -.mdc-thing { +.my-element { transition: mdc-animation-exit-permanent(/* $name: */ opacity, /* $duration: */ 175ms, /* $delay: */ 150ms); opacity: 0; will-change: opacity; - &:active { - transition: mdc-animation-enter(opacity, 175ms /*, $delay: 0ms by default */); + &--animating { + transition: mdc-animation-enter(/* $name: */ opacity, /* $duration: */ 175ms); opacity: 1; } } ``` -Note that these functions also work with the `animation` property. ```scss -@import "@material/animation/functions"; - @keyframes fade-in { from { transform: translateY(-80px); @@ -92,44 +101,28 @@ Note that these functions also work with the `animation` property. } } -.mdc-thing { - animation: mdc-animation-enter(fade-in, 350ms); +.my-element { + animation: mdc-animation-enter(/* $name: */ fade-in, /* $duration: */ 350ms); } ``` -### CSS Classes - -> NOTE: dist/ will be available when installing via NPM. - -Alternatively, you can include the built stylesheet and use the classes it exports within your HTML - -```html - - -
hi
-``` - -CSS Classes have the exact same name as their mixin counterparts. - -### Overriding the default curves. - -All animation variables are marked with `!default`, thus they can be overridden should the need -arise. +Function | Description +--- | --- +`mdc-animation-enter($name, $duration, $delay)` | Defines transition for entering the frame +`mdc-animation-exit-permanent($name, $duration, $delay)` | Defines transition for exiting the frame permanently +`mdc-animation-exit-temporary($name, $duration, $delay)` | Defines transition for exiting the frame temporarily ### JavaScript -MDC Web ships with a set of utility functions designed to make animations easier to implement. - -### Using Utility Functions +These functions handle prefixing across various browsers -To use: ```js import {getCorrectEventName} from '@material/animation'; const eventToListenFor = getCorrectEventName(window, 'animationstart'); ``` -| Method Signature | Description | -| --- | --- | -| `getCorrectEventName(windowObj: Object, eventType: string)` | Returns a JavaScript event name. Prefixed if necessary. | -| `getCorrectPropertyName(windowObj: Object, eventType: string)` | Returns a CSS property name. Prefixed if necessary. | +Method Signature | Description +--- | --- +`getCorrectEventName(windowObj, eventType)` | Returns a JavaScript event name, prefixed if necessary | +`getCorrectPropertyName(windowObj, eventType)` | Returns a CSS property name, prefixed if necessary | From 559f9218e9a06cb537a4eaf23a08ca6decd62326 Mon Sep 17 00:00:00 2001 From: lynnjepsen Date: Wed, 2 Aug 2017 13:07:20 -0700 Subject: [PATCH 2/3] update first sentence and add imports --- packages/mdc-animation/README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/packages/mdc-animation/README.md b/packages/mdc-animation/README.md index 9f64089a9a6..5a1e7516ef8 100644 --- a/packages/mdc-animation/README.md +++ b/packages/mdc-animation/README.md @@ -29,9 +29,9 @@ npm install --save @material/animation ### CSS Classes -Some components have a set typographic style. For example, a raised MDC Checkbox enter and exit curves. +Some components already use a set curve for their animation. For example, MDC Checkbox uses deceleration curve for its checkmark animation. -If you want to animate an element, which is not a Material Design component, you can apply the following CSS classes. +If you want to animate an element that is not a Material Design component, you can apply the following CSS classes. CSS Class | Description --- | --- @@ -45,6 +45,8 @@ CSS Class | Description Instead of setting CSS classes on elements, you can use the Sass mixins to achieve the same goal. ```scss +@import "@material/animation/mixins"; + .my-element--animating { @include mdc-animation-acceleration-curve; } @@ -60,6 +62,8 @@ Mixin | Description We also provide the timing functions used by these mixins, which you can use with the `animation` or `transition` CSS properties ```scss +@import "@material/animation/variables"; + .my-element--animating { animation: foo-keyframe 175ms $mdc-animation-standard-curve-timing-function; } @@ -75,6 +79,8 @@ Variable | Description The following functions create transitions given `$name` and the `$duration`. You can also specify `$delay`, but the default is 0ms. `$name` can either refer to the keyframe, or to CSS property used in `transition`. ```scss +@import "@material/animation/functions"; + .my-element { transition: mdc-animation-exit-permanent(/* $name: */ opacity, /* $duration: */ 175ms, /* $delay: */ 150ms); opacity: 0; @@ -89,6 +95,8 @@ The following functions create transitions given `$name` and the `$duration`. Yo ```scss +@import "@material/animation/functions"; + @keyframes fade-in { from { transform: translateY(-80px); @@ -124,5 +132,5 @@ const eventToListenFor = getCorrectEventName(window, 'animationstart'); Method Signature | Description --- | --- -`getCorrectEventName(windowObj, eventType)` | Returns a JavaScript event name, prefixed if necessary | -`getCorrectPropertyName(windowObj, eventType)` | Returns a CSS property name, prefixed if necessary | +`getCorrectEventName(windowObj, eventType)` | Returns a JavaScript event name, prefixed if necessary +`getCorrectPropertyName(windowObj, eventType)` | Returns a CSS property name, prefixed if necessary From f4cc68a4a5902c9ecd8c34e9d20b54c47167ce65 Mon Sep 17 00:00:00 2001 From: lynnjepsen Date: Wed, 2 Aug 2017 13:41:15 -0700 Subject: [PATCH 3/3] add animation-timing-function to description --- packages/mdc-animation/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/mdc-animation/README.md b/packages/mdc-animation/README.md index 5a1e7516ef8..7f4a34765ef 100644 --- a/packages/mdc-animation/README.md +++ b/packages/mdc-animation/README.md @@ -35,10 +35,10 @@ If you want to animate an element that is not a Material Design component, you c CSS Class | Description --- | --- -`mdc-animation-deceleration-curve` | Sets the speed curve to deceleration -`mdc-animation-standard-curve` | Sets the speed curve to standard, a.k.a quickly accelerate and slowly decelerate -`mdc-animation-acceleration-curve` | Sets the speed curve to acceleration -`mdc-animation-sharp-curve` | Sets the speed curve to sharp, a.k.a quickly accelerate and decelerate +`mdc-animation-deceleration-curve` | Sets the `animation-timing-function` to deceleration curve +`mdc-animation-standard-curve` | Sets the `animation-timing-function` to standard curve, a.k.a quickly accelerate and slowly decelerate +`mdc-animation-acceleration-curve` | Sets the `animation-timing-function` to acceleration curve +`mdc-animation-sharp-curve` | Sets the `animation-timing-function` to shar curve, a.k.a quickly accelerate and decelerate ### Sass Variables and Mixins @@ -54,10 +54,10 @@ Instead of setting CSS classes on elements, you can use the Sass mixins to achie Mixin | Description --- | --- -`mdc-animation-deceleration-curve` | Sets the speed curve to deceleration -`mdc-animation-standard-curve` | Sets the speed curve to standard, a.k.a quickly accelerate and slowly decelerate -`mdc-animation-acceleration-curve` | Sets the speed curve to acceleration -`mdc-animation-sharp-curve` | Sets the speed curve to sharp, a.k.a quickly accelerate and decelerate +`mdc-animation-deceleration-curve` | Sets the `animation-timing-function` to deceleration curve +`mdc-animation-standard-curve` | Sets the `animation-timing-function` to standard curve, a.k.a quickly accelerate and slowly decelerate +`mdc-animation-acceleration-curve` | Sets the `animation-timing-function` to acceleration curve +`mdc-animation-sharp-curve` | Sets the `animation-timing-function` to shar curve, a.k.a quickly accelerate and decelerate We also provide the timing functions used by these mixins, which you can use with the `animation` or `transition` CSS properties