diff --git a/docs/designers-developers/designers/animation.md b/docs/designers-developers/designers/animation.md
new file mode 100644
index 0000000000000..66664639d3a23
--- /dev/null
+++ b/docs/designers-developers/designers/animation.md
@@ -0,0 +1,33 @@
+# Animation
+
+Animation can help reinforce a sense of hierarchy and spatial orientation. This document goes into principles you should follow when you add animation.
+
+## Principles
+
+### Point of Origin
+
+- Animation can help anchor an interface element. For example a menu can scale up from the button that opened it.
+- Animation can help give a sense of place; for example a sidebar can animate in from the side, implying it was always hidden off-screen.
+- Design your animations as if you're working with real-world materials. Imagine your user interface elements are made of real materials — when not on screen, where are they? Use animation to help express that.
+
+### Speed
+
+- Animations should never block a user interaction. They should be fast, almost always complete in less than 0.2 seconds.
+- A user should not have to wait for an animation to finish before they can interact.
+- Animations should be performant. Use `transform` CSS properties when you can, these render elements on the GPU, making them smooth.
+- If an animation can't be made fast & performant, leave it out.
+
+### Simple
+
+- Don't bounce if the material isn't made of rubber.
+- Don't rotate, fold, or animate on a curved path. Keep it simple.
+
+### Consistency
+
+In creating consistent animations, we have to establish physical rules for how elements behave when animated. When all animations follow these rules, they feel consistent, related, and predictable. An animation should match user expectations, if it doesn't, it's probably not the right animation for the job.
+
+Reuse animations if one already exists for your task.
+
+## Inventory of Reused Animations
+
+The generic `Animate` component is used to animate different parts of the interface. See [the component documentation](/packages/components/src/animate/README.md) for more details about the available animations.
diff --git a/docs/manifest.json b/docs/manifest.json
index 6e6dbd2e40251..f3795c17d0900 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -371,6 +371,12 @@
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/design-resources.md",
"parent": "designers"
},
+ {
+ "title": "Animation",
+ "slug": "animation",
+ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/animation.md",
+ "parent": "designers"
+ },
{
"title": "Contributors Guide",
"slug": "contributors",
@@ -809,6 +815,12 @@
"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/wordcount/README.md",
"parent": "packages"
},
+ {
+ "title": "Animate",
+ "slug": "animate",
+ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/animate/README.md",
+ "parent": "components"
+ },
{
"title": "Autocomplete",
"slug": "autocomplete",
diff --git a/docs/toc.json b/docs/toc.json
index 14bed66d0a75e..2db354115f8f0 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -71,7 +71,8 @@
{"docs/designers-developers/designers/README.md": [
{"docs/designers-developers/designers/block-design.md": []},
{"docs/designers-developers/designers/design-patterns.md": []},
- {"docs/designers-developers/designers/design-resources.md": []}
+ {"docs/designers-developers/designers/design-resources.md": []},
+ {"docs/designers-developers/designers/animation.md": []}
]}
]},
{"docs/contributors/readme.md": [
diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 427e5aa90759a..8dbce2d719be7 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -1,5 +1,9 @@
## 7.1.0 (Unreleased)
+### New Features
+
+- Added a new `Animate` component.
+
### Improvements
- `withFilters` has been optimized to avoid binding hook handlers for each mounted instance of the component, instead using a single centralized hook delegator.
diff --git a/packages/components/src/animate/README.md b/packages/components/src/animate/README.md
new file mode 100644
index 0000000000000..5ad580bac51e6
--- /dev/null
+++ b/packages/components/src/animate/README.md
@@ -0,0 +1,39 @@
+# Animate
+
+Simple interface to introduce animations to components.
+
+## Usage
+
+```jsx
+import { Animate } from '@wordpress/components';
+
+const MyAnimatedNotice = () => (
+
+ { ( { className } ) => (
+
+
Animation finished.
+
+ ) }
+
+);
+```
+
+## Props
+
+Name | Type | Default | Description
+--- | --- | --- | ---
+`type` | `string` | `undefined` | Type of the animation to use.
+`options` | `object` | `{}` | Options of the chosen animation.
+`children` | `function` | `undefined` | A callback receiving a list of props ( `className` ) to apply to the DOM element to animate.
+
+## Available Animation Types
+
+### appear
+
+This animation is meant for popover/modal content, such as menus appearing. It shows the height and width of the animated element scaling from 0 to full size, from its point of origin.
+
+#### Options
+
+Name | Type | Default | Description
+--- | --- | --- | ---
+`origin` | `string` | `top center` | Point of origin (`top`, `bottom`,` middle right`, `left`, `center`).
diff --git a/packages/components/src/animate/index.js b/packages/components/src/animate/index.js
new file mode 100644
index 0000000000000..a144e6ee8b27d
--- /dev/null
+++ b/packages/components/src/animate/index.js
@@ -0,0 +1,25 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+function Animate( { type, options = {}, children } ) {
+ if ( type === 'appear' ) {
+ const { origin = 'top' } = options;
+ const [ yAxis, xAxis = 'center' ] = origin.split( ' ' );
+
+ return children( {
+ className: classnames(
+ 'components-animate__appear',
+ {
+ [ 'is-from-' + xAxis ]: xAxis !== 'center',
+ [ 'is-from-' + yAxis ]: yAxis !== 'middle',
+ },
+ ),
+ } );
+ }
+
+ return children( {} );
+}
+
+export default Animate;
diff --git a/packages/components/src/animate/style.scss b/packages/components/src/animate/style.scss
new file mode 100644
index 0000000000000..0a725ce0032d4
--- /dev/null
+++ b/packages/components/src/animate/style.scss
@@ -0,0 +1,28 @@
+.components-animate__appear {
+ animation: components-animate__appear-animation 0.1s cubic-bezier(0, 0, 0.2, 1) 0s;
+ animation-fill-mode: forwards;
+
+ &.is-from-top,
+ &.is-from-top.is-from-left {
+ transform-origin: top left;
+ }
+ &.is-from-top.is-from-right {
+ transform-origin: top right;
+ }
+ &.is-from-bottom,
+ &.is-from-bottom.is-from-left {
+ transform-origin: bottom left;
+ }
+ &.is-from-bottom.is-from-right {
+ transform-origin: bottom right;
+ }
+}
+
+@keyframes components-animate__appear-animation {
+ from {
+ transform: translateY(-2em) scaleY(0) scaleX(0);
+ }
+ to {
+ transform: translateY(0%) scaleY(1) scaleX(1);
+ }
+}
diff --git a/packages/components/src/index.js b/packages/components/src/index.js
index f892867c7a400..2bc81c542f019 100644
--- a/packages/components/src/index.js
+++ b/packages/components/src/index.js
@@ -1,6 +1,7 @@
// Components
export * from './primitives';
// eslint-disable-next-line camelcase
+export { default as Animate } from './animate';
export { default as Autocomplete } from './autocomplete';
export { default as BaseControl } from './base-control';
export { default as Button } from './button';
diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js
index 643d032984181..052e53189ba84 100644
--- a/packages/components/src/popover/index.js
+++ b/packages/components/src/popover/index.js
@@ -22,6 +22,7 @@ import IconButton from '../icon-button';
import ScrollLock from '../scroll-lock';
import IsolatedEventContainer from '../isolated-event-container';
import { Slot, Fill, Consumer } from '../slot-fill';
+import Animate from '../animate';
const FocusManaged = withConstrainedTabbing( withFocusReturn( ( { children } ) => children ) );
@@ -55,6 +56,11 @@ class Popover extends Component {
contentWidth: null,
isMobile: false,
popoverSize: null,
+
+ // Delay the animation after the initial render
+ // because the animation have impact on the height of the popover
+ // causing the computed position to be wrong.
+ isReadyToAnimate: false,
};
// Property used keep track of the previous anchor rect
@@ -150,7 +156,7 @@ class Popover extends Component {
popoverSize.height !== this.state.popoverSize.height
);
if ( didPopoverSizeChange ) {
- this.setState( { popoverSize } );
+ this.setState( { popoverSize, isReadyToAnimate: true } );
}
this.anchorRect = anchorRect;
this.computePopoverPosition( popoverSize, anchorRect );
@@ -258,6 +264,7 @@ class Popover extends Component {
focusOnMount,
getAnchorRect,
expandOnMobile,
+ animate = true,
/* eslint-enable no-unused-vars */
...contentProps
} = this.props;
@@ -270,8 +277,21 @@ class Popover extends Component {
contentWidth,
popoverSize,
isMobile,
+ isReadyToAnimate,
} = this.state;
+ // Compute the animation position
+ const yAxisMapping = {
+ top: 'bottom',
+ bottom: 'top',
+ };
+ const xAxisMapping = {
+ left: 'right',
+ right: 'left',
+ };
+ const animateYAxis = yAxisMapping[ yAxis ] || 'middle';
+ const animateXAxis = xAxisMapping[ xAxis ] || 'center';
+
const classes = classnames(
'components-popover',
className,
@@ -289,36 +309,43 @@ class Popover extends Component {
/* eslint-disable jsx-a11y/no-static-element-interactions */
let content = (
-
- { isMobile && (
-