Try menu appear animation & start work on handbook

docs/designers-developers/designers/animation.md

@@ -0,0 +1,65 @@
+# 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 curve. 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 following is a running list of existing animations, and how they fit with the above principles. 
+
+### `edit-post__loading-fade-animation`
+
+A "pulsing fade" animation that is used when an element is _transient_. For example when an image is being uploaded. It is simple, and indicates background work.
+
+### `edit-post__fade-in-animation`
+
+The most basic fade-in animation. It simply fades from transparent to opaque.
+
+### `components-button__busy-animation`
+
+When a button is working, this animation adds a set of diagonal stripes that animate from left to right. 
+
+### `components-modal__appear-animation`
+
+Modal windows are cards that live below the viewport. When invoked, they animate in front of the button and upwards. Because of their relative size, this is a very brief fade animation. 
+
+### `components-spinner__animation`
+
+A simple rotation used for a loading-state spinner.
+
+### `edit-post-fullscreen-mode__slide-in-animation`
+
+When you enter fullscreen mode, the editor bar animates downwards from the top.
+
+### `edit-post-layout__slide-in-animation`
+
+The Publish sidebar lives to the right of the viewport. When you press the "Publish..." button, it slides in from the right.
+
+### `nux-pulse`
+
+This animation is used for the dot indicators that appear in the out of box experience. They create a "pulsing" effect behind the dot indicators.

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;

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);
+	}
+}

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';

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 = (
 			<PopoverDetectOutside onClickOutside={ onClickOutside }>
-				<IsolatedEventContainer
-					className={ classes }
-					style={ {
-						top: ! isMobile && popoverTop ? popoverTop + 'px' : undefined,
-						left: ! isMobile && popoverLeft ? popoverLeft + 'px' : undefined,
-						visibility: popoverSize ? undefined : 'hidden',
-					} }
-					{ ...contentProps }
-					onKeyDown={ this.maybeClose }
+				<Animate
+					type={ animate && isReadyToAnimate ? 'appear' : null }
+					options={ { origin: animateYAxis + ' ' + animateXAxis } }
 				>
-					{ isMobile && (
-						<div className="components-popover__header">
-							<span className="components-popover__header-title">
-								{ headerTitle }
-							</span>
-							<IconButton className="components-popover__close" icon="no-alt" onClick={ onClose } />
-						</div>
+					{ ( { className: animateClassName } ) => (
+						<IsolatedEventContainer
+							className={ classnames( classes, animateClassName ) }
+							style={ {
+								top: ! isMobile && popoverTop ? popoverTop + 'px' : undefined,
+								left: ! isMobile && popoverLeft ? popoverLeft + 'px' : undefined,
+								visibility: popoverSize ? undefined : 'hidden',
+							} }
+							{ ...contentProps }
+							onKeyDown={ this.maybeClose }
+						>
+							{ isMobile && (
+								<div className="components-popover__header">
+									<span className="components-popover__header-title">
+										{ headerTitle }
+									</span>
+									<IconButton className="components-popover__close" icon="no-alt" onClick={ onClose } />
+								</div>
+							) }
+							<div
+								ref={ this.contentNode }
+								className="components-popover__content"
+								style={ {
+									maxHeight: ! isMobile && contentHeight ? contentHeight + 'px' : undefined,
+									maxWidth: ! isMobile && contentWidth ? contentWidth + 'px' : undefined,
+								} }
+								tabIndex="-1"
+							>
+								{ children }
+							</div>
+						</IsolatedEventContainer>
 					) }
-					<div
-						ref={ this.contentNode }
-						className="components-popover__content"
-						style={ {
-							maxHeight: ! isMobile && contentHeight ? contentHeight + 'px' : undefined,
-							maxWidth: ! isMobile && contentWidth ? contentWidth + 'px' : undefined,
-						} }
-						tabIndex="-1"
-					>
-						{ children }
-					</div>
-				</IsolatedEventContainer>
+				</Animate>
 			</PopoverDetectOutside>
 		);
 		/* eslint-enable jsx-a11y/no-static-element-interactions */

packages/components/src/style.scss

@@ -1,3 +1,4 @@
+@import "./animate//style.scss";
 @import "./autocomplete/style.scss";
 @import "./base-control/style.scss";
 @import "./button-group/style.scss";

packages/components/src/tooltip/index.js

@@ -115,6 +115,7 @@ class Tooltip extends Component {
 						position={ position }
 						className="components-tooltip"
 						aria-hidden="true"
+						animate={ false }
 					>
 						{ text }
 						<Shortcut className="components-tooltip__shortcut" shortcut={ shortcut } />