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

@@ -111,6 +111,7 @@ const BlockDraggable = ( { children, clientId, blockName, blockElementId, onDrag
 			transferData={ transferData }
 			onDragStart={ onDragStart }
 			onDragEnd={ onDragEnd }
+			clientId={ clientId }
 			clearHighlight={ clearHighlight }
 			setHighlightByOffset={ setHighlightByOffset }
 			dropElementByOffset={ dropElementByOffset }

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,20 +12,23 @@ 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 withSnapTargets from '../higher-order/with-snap-targets';
 import {
 	getPixelsFromPercentage,
 	getPercentageFromPixels,
 	getRelativeElementPosition,
 	isCTABlock,
 } from '../../helpers';
+import { getBestSnapLines } from '../../helpers/snapping';
 import {
 	STORY_PAGE_INNER_WIDTH,
 	STORY_PAGE_INNER_HEIGHT,
+	BLOCK_DRAGGING_SNAP_GAP,
 	STORY_PAGE_INNER_HEIGHT_FOR_CTA,
 	STORY_PAGE_MARGIN,
 } from '../../constants';
@@ -39,6 +42,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 );
@@ -70,7 +76,7 @@ class Draggable extends Component {
 	 * @param {Object} event The non-custom DragEvent.
 	 */
 	onDragEnd = ( event ) => {
-		const { clearHighlight, dropElementByOffset, blockName, setTimeout, onDragEnd = noop } = this.props;
+		const { clearHighlight, dropElementByOffset, blockName, setTimeout, clearSnapLines, onDragEnd = noop } = this.props;
 		if ( event ) {
 			event.preventDefault();
 		}
@@ -104,6 +110,9 @@ class Draggable extends Component {
 		}
 
 		this.resetDragState();
+
+		clearSnapLines();
+
 		setTimeout( onDragEnd );
 	}
 
@@ -112,9 +121,48 @@ class Draggable extends Component {
 	 *
 	 * @param  {Object} event The non-custom DragEvent.
 	 */
-	onDragOver = ( event ) => {
-		const { setHighlightByOffset, blockName } = this.props;
+	onDragOver = ( event ) => { // eslint-disable-line complexity
+		const {
+			blockName,
+			setSnapLines,
+			clearSnapLines,
+			parentBlockElement,
+			horizontalSnaps,
+			verticalSnaps,
+			setHighlightByOffset,
+		} = 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;
+		}
+
+		// 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( blockName ) ? 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 snappingEnabled = ! event.getModifierState( 'Alt' );
+
+		if ( snappingEnabled ) {
+			const horizontalSnapsForPosition = horizontalSnaps( actualTop, actualBottom );
+			const verticalSnapsForPosition = verticalSnaps( actualLeft, actualRight );
+			setSnapLines( [
+				...getBestSnapLines( horizontalSnapsForPosition, actualLeft, actualRight, BLOCK_DRAGGING_SNAP_GAP ),
+				...getBestSnapLines( verticalSnapsForPosition, actualTop, actualBottom, BLOCK_DRAGGING_SNAP_GAP ),
+			] );
+		} else {
+			clearSnapLines();
+		}
 
 		// Don't allow the CTA button to go over its top limit.
 		if ( isCTABlock( blockName ) ) {
@@ -123,13 +171,15 @@ 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;
+
 		// Check if mouse (*not* element, but actual cursor) is over neighboring page to either side.
 		const currentElementLeft = parseInt( this.cloneWrapper.style.left );
 		const cursorLeftRelativeToPage = currentElementLeft + this.cursorLeftInsideElement;
@@ -143,6 +193,7 @@ class Draggable extends Component {
 				Math.ceil( ( cursorLeftRelativeToPage - PAGE_AND_MARGIN ) / PAGE_AND_MARGIN )
 			);
 		}
+
 		setHighlightByOffset( this.pageOffset );
 	}
 
@@ -160,7 +211,13 @@ 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,
+			clearSnapLines,
+		} = this.props;
 		const blockIsCTA = isCTABlock( blockName );
 		// In the CTA block only the inner element (the button) is draggable, not the whole block.
 		const element = blockIsCTA ? document.getElementById( elementId ) : document.getElementById( elementId ).parentNode;
@@ -199,6 +256,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.
@@ -229,6 +287,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 );
@@ -244,6 +303,8 @@ class Draggable extends Component {
 			document.addEventListener( 'drop', this.onDrop );
 		}
 
+		clearSnapLines();
+
 		this.props.setTimeout( onDragStart );
 	}
 
@@ -294,6 +355,16 @@ Draggable.propTypes = {
 	dropElementByOffset: PropTypes.func.isRequired,
 	setTimeout: PropTypes.func.isRequired,
 	children: PropTypes.func.isRequired,
+	horizontalSnaps: PropTypes.func.isRequired,
+	verticalSnaps: PropTypes.func.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}
+/>
+`;