Snapping Guidelines

.eslintrc

@@ -30,6 +30,12 @@
     "no-template-curly-in-string": "error",
     "no-throw-literal": "error",
     "no-unmodified-loop-condition": "error",
+    "no-unused-vars": [
+      "error",
+      {
+        "ignoreRestSiblings": true,
+      }
+    ],
     "no-useless-call": "error",
     "no-useless-concat": "error",
     "prefer-object-spread": "error",

assets/src/stories-editor/components/block-mover/block-draggable.js

@@ -32,6 +32,7 @@ const BlockDraggable = ( { children, clientId, blockName, rootClientId, blockEle
 			transferData={ transferData }
 			onDragStart={ onDragStart }
 			onDragEnd={ onDragEnd }
+			clientId={ clientId }
 		>
 			{
 				( { onDraggableStart, onDraggableEnd } ) => {
@@ -51,7 +52,7 @@ BlockDraggable.propTypes = {
 	clientId: PropTypes.string,
 	blockElementId: PropTypes.string,
 	blockName: PropTypes.string,
-	children: PropTypes.node.isRequired,
+	children: PropTypes.func.isRequired,
 	onDragStart: PropTypes.func,
 	onDragEnd: PropTypes.func,
 };

assets/src/stories-editor/components/block-mover/draggable.js

@@ -1,5 +1,5 @@
 /**
- * This file is based on the core's <Draggable> Component.
+ * This file is based on core's <Draggable> Component.
  **/
 
 /**
@@ -12,15 +12,21 @@ import PropTypes from 'prop-types';
  * WordPress dependencies
  */
 import { Component } from '@wordpress/element';
-import { withSafeTimeout } from '@wordpress/compose';
+import { withSafeTimeout, compose } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
-import { getPixelsFromPercentage } from '../../helpers';
+import withSnapTargets from '../higher-order/with-snap-targets';
+import {
+	getPixelsFromPercentage,
+	findClosestSnap,
+	getRelativeElementPosition,
+} from '../../helpers';
 import {
 	STORY_PAGE_INNER_WIDTH,
 	STORY_PAGE_INNER_HEIGHT,
+	BLOCK_DRAGGING_SNAP_GAP,
 } from '../../constants';
 
 const { Image, navigator } = window;
@@ -30,6 +36,9 @@ const cloneWrapperClass = 'components-draggable__clone';
 const isChromeUA = ( ) => /Chrome/i.test( navigator.userAgent );
 const documentHasIframes = ( ) => [ ...document.getElementById( 'editor' ).querySelectorAll( 'iframe' ) ].length > 0;
 
+let lastX;
+let lastY;
+
 class Draggable extends Component {
 	constructor( ...args ) {
 		super( ...args );
@@ -61,12 +70,17 @@ class Draggable extends Component {
 	 * @param {Object} event The non-custom DragEvent.
 	 */
 	onDragEnd = ( event ) => {
-		const { onDragEnd = noop } = this.props;
+		const { onDragEnd = noop, snapLines, clearSnapLines } = this.props;
 		if ( event ) {
 			event.preventDefault();
 		}
 
 		this.resetDragState();
+
+		if ( snapLines.length ) {
+			clearSnapLines();
+		}
+
 		this.props.setTimeout( onDragEnd );
 	}
 
@@ -75,8 +89,81 @@ class Draggable extends Component {
 	 *
 	 * @param  {Object} event The non-custom DragEvent.
 	 */
-	onDragOver = ( event ) => {
+	onDragOver = ( event ) => { // eslint-disable-line complexity
+		const {
+			blockName,
+			snapLines,
+			clearSnapLines,
+			setSnapLines,
+			parentBlockElement,
+			horizontalSnaps,
+			verticalSnaps,
+		} = this.props;
+
 		const top = parseInt( this.cloneWrapper.style.top ) + event.clientY - this.cursorTop;
+		const left = parseInt( this.cloneWrapper.style.left ) + event.clientX - this.cursorLeft;
+
+		if ( top === lastY && left === lastX ) {
+			return;
+		}
+
+		const isCTABlock = 'amp/amp-story-cta' === blockName;
+
+		// Get the correct dimensions in case the block is rotated, as rotation is only applied to the clone's inner element(s).
+		// For CTA blocks, not the whole block is draggable, but only the button within.
+		const blockElement = isCTABlock ? this.cloneWrapper.querySelector( '.amp-story-cta-button' ) : this.cloneWrapper.querySelector( '.wp-block' );
+
+		// We calculate with the block's actual dimensions relative to the page it's on.
+		const {
+			top: actualTop,
+			right: actualRight,
+			bottom: actualBottom,
+			left: actualLeft,
+		} = getRelativeElementPosition( blockElement, parentBlockElement );
+
+		const horizontalCenter = ( actualRight + actualLeft ) / 2;
+		const verticalCenter = ( actualTop + actualBottom ) / 2;
+
+		const newSnapLines = [];
+
+		const snappingEnabled = ! event.getModifierState( 'Alt' );
+
+		if ( snappingEnabled ) {
+			// Go through all snap targets and find the one that is closest.
+			const findSnap = ( snapKeys, ...values ) => {
+				return values
+					.map( ( value ) => {
+						const snap = findClosestSnap( value, snapKeys, BLOCK_DRAGGING_SNAP_GAP );
+						return [ value, snap ];
+					} )
+					.filter( ( arr ) => arr[ 1 ] !== null )
+					.sort( ( a, b ) => a[ 1 ] - b[ 1 ] )
+					.map( ( arr ) => arr[ 1 ] )
+					.shift();
+			};
+
+			const _horizontalSnaps = horizontalSnaps( actualTop, actualBottom );
+			const _horizontalSnapKeys = Object.keys( _horizontalSnaps );
+			const _verticalSnaps = verticalSnaps( actualLeft, actualRight );
+			const _verticalSnapKeys = Object.keys( _verticalSnaps );
+
+			const horizontalSnap = findSnap( _horizontalSnapKeys, actualLeft, actualRight, horizontalCenter );
+			const verticalSnap = findSnap( _verticalSnapKeys, actualTop, actualBottom, verticalCenter );
+
+			if ( horizontalSnap !== undefined ) {
+				newSnapLines.push( ..._horizontalSnaps[ horizontalSnap ] );
+			}
+
+			if ( verticalSnap !== undefined ) {
+				newSnapLines.push( ..._verticalSnaps[ verticalSnap ] );
+			}
+		}
+
+		if ( newSnapLines.length ) {
+			setSnapLines( newSnapLines );
+		} else if ( snapLines.length ) {
+			clearSnapLines();
+		}
 
 		// Don't allow the CTA button to go over its top limit.
 		if ( 'amp/amp-story-cta' === this.props.blockName ) {
@@ -85,12 +172,14 @@ class Draggable extends Component {
 			this.cloneWrapper.style.top = `${ top }px`;
 		}
 
-		this.cloneWrapper.style.left =
-			`${ parseInt( this.cloneWrapper.style.left ) + event.clientX - this.cursorLeft }px`;
+		this.cloneWrapper.style.left = `${ left }px`;
 
 		// Update cursor coordinates.
 		this.cursorLeft = event.clientX;
 		this.cursorTop = event.clientY;
+
+		lastY = top;
+		lastX = left;
 	}
 
 	onDrop = () => {
@@ -107,7 +196,14 @@ class Draggable extends Component {
 	 * @param {Object} event Custom DragEvent.
 	 */
 	onDragStart = ( event ) => {
-		const { blockName, elementId, transferData, onDragStart = noop } = this.props;
+		const {
+			blockName,
+			elementId,
+			transferData,
+			onDragStart = noop,
+			snapLines,
+			clearSnapLines,
+		} = this.props;
 		const isCTABlock = 'amp/amp-story-cta' === blockName;
 		// In the CTA block only the inner element (the button) is draggable, not the whole block.
 		const element = isCTABlock ? document.getElementById( elementId ) : document.getElementById( elementId ).parentNode;
@@ -146,6 +242,7 @@ class Draggable extends Component {
 		this.cloneWrapper.style.height = `${ element.clientHeight }px`;
 
 		const clone = element.cloneNode( true );
+
 		this.cloneWrapper.style.transform = clone.style.transform;
 
 		// 20% of the full value in case of CTA block.
@@ -169,6 +266,7 @@ class Draggable extends Component {
 		// Mark the current cursor coordinates.
 		this.cursorLeft = event.clientX;
 		this.cursorTop = event.clientY;
+
 		// Update cursor to 'grabbing', document wide.
 		document.body.classList.add( 'is-dragging-components-draggable' );
 		document.addEventListener( 'dragover', this.onDragOver );
@@ -184,6 +282,10 @@ class Draggable extends Component {
 			document.addEventListener( 'drop', this.onDrop );
 		}
 
+		if ( snapLines.length ) {
+			clearSnapLines();
+		}
+
 		this.props.setTimeout( onDragStart );
 	}
 
@@ -230,7 +332,18 @@ Draggable.propTypes = {
 	onDragStart: PropTypes.func,
 	onDragEnd: PropTypes.func,
 	setTimeout: PropTypes.func.isRequired,
-	children: PropTypes.node.isRequired,
+	children: PropTypes.func.isRequired,
+	horizontalSnaps: PropTypes.func.isRequired,
+	verticalSnaps: PropTypes.func.isRequired,
+	snapLines: PropTypes.array.isRequired,
+	setSnapLines: PropTypes.func.isRequired,
+	clearSnapLines: PropTypes.func.isRequired,
+	parentBlockElement: PropTypes.object,
 };
 
-export default withSafeTimeout( Draggable );
+const enhance = compose(
+	withSnapTargets,
+	withSafeTimeout,
+);
+
+export default enhance( Draggable );

assets/src/stories-editor/components/block-mover/edit.css

@@ -34,3 +34,12 @@
 .wp-block[data-type="core/quote"] .editor-rich-text__editable:hover {
 	cursor: default;
 }
+
+.components-draggable__clone .components-resizable-box__handle,
+.components-draggable__clone .rotatable-box-wrap::before,
+.components-draggable__clone .rotatable-box-wrap__handle {
+	display: none;
+	opacity: 0;
+	visibility: hidden;
+	content: none;
+}

assets/src/stories-editor/components/contexts/snapping.js

@@ -0,0 +1,77 @@
+/**
+ * External dependencies
+ */
+import PropTypes from 'prop-types';
+
+/**
+ * WordPress dependencies
+ */
+import { SVG } from '@wordpress/components';
+import { createHigherOrderComponent } from '@wordpress/compose';
+import { createContext, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { STORY_PAGE_INNER_HEIGHT, STORY_PAGE_INNER_WIDTH } from '../../constants';
+
+const SnapContext = createContext();
+
+const Snapping = ( { children } ) => {
+	const [ snapLines, setSnapLines ] = useState( [] );
+
+	const clearSnapLines = () => setSnapLines( [] );
+
+	const context = {
+		setSnapLines,
+		snapLines,
+		clearSnapLines,
+	};
+
+	return (
+		<SnapContext.Provider value={ context }>
+			{ children }
+			{ Boolean( snapLines.length ) && (
+				<SVG
+					viewBox={ `0 0 ${ STORY_PAGE_INNER_WIDTH } ${ STORY_PAGE_INNER_HEIGHT }` }
+					style={ {
+						position: 'absolute',
+						top: 0,
+						pointerEvents: 'none',
+					} }
+				>
+					{ snapLines.map( ( [ [ x1, y1 ], [ x2, y2 ] ], index ) => (
+						<line
+							key={ index }
+							x1={ x1 }
+							y1={ y1 }
+							x2={ x2 }
+							y2={ y2 }
+							stroke="red"
+							pointerEvents="none"
+						/>
+					) ) }
+				</SVG>
+			) }
+		</SnapContext.Provider>
+	);
+};
+
+Snapping.propTypes = {
+	children: PropTypes.object,
+};
+
+export default Snapping;
+
+export const withSnapContext = createHigherOrderComponent(
+	( WrappedComponent ) => ( props ) => (
+		<SnapContext.Consumer>
+			{
+				( snappingProps ) => (
+					<WrappedComponent { ...props } { ...snappingProps } />
+				)
+			}
+		</SnapContext.Consumer>
+	),
+	'withSnapContext',
+);

assets/src/stories-editor/components/contexts/test/__snapshots__/snapping.js.snap

@@ -0,0 +1,13 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Snapping should render a single snap line correctly when set 1`] = `
+<line
+  key="0"
+  pointerEvents="none"
+  stroke="red"
+  x1={0}
+  x2={100}
+  y1={100}
+  y2={100}
+/>
+`;