Update BlockMover Stories and README

packages/block-editor/src/components/block-mover/README.md

@@ -1,12 +1,10 @@
-# Block mover
+# BlockMover
 
-Block movers allow moving blocks inside the editor using up and down buttons.
+BlockMover component allows moving blocks inside the editor using up and down buttons.
 
 ![Block mover screenshot](https://make.wordpress.org/core/files/2020/08/block-mover-screenshot.png)
 
-## Development guidelines
-
-### Usage
+## Usage
 
 Shows the block mover buttons in the block toolbar.
 
@@ -15,13 +13,22 @@ import { BlockMover } from '@wordpress/block-editor';
 const MyMover = () => <BlockMover clientIds={ [ clientId ] } />;
 ```
 
-### Props
+## Props
 
-#### clientIds
+### clientIds
 
-Blocks IDs
+The IDs of the blocks to move.
 
 -   Type: `Array`
+-   Required: Yes
+
+### hideDragHandle
+
+If this property is true, the drag handle is hidden.
+
+-   Type: `boolean`
+-   Required: No
+-   Default: `false`
 
 ## Related components
 

packages/block-editor/src/components/block-mover/stories/index.story.js

@@ -14,6 +14,7 @@ import BlockMover from '../';
 import { ExperimentalBlockEditorProvider } from '../../provider';
 import { store as blockEditorStore } from '../../../store';
 
+// For the purpose of this story, we need to register the core blocks samples.
 registerCoreBlocks();
 const blocks = [
 	// vertical
@@ -30,81 +31,113 @@ const blocks = [
 	] ),
 ];
 
-function Provider( { children } ) {
-	const wrapperStyle = { margin: '24px', position: 'relative' };
-
-	return (
-		<div style={ wrapperStyle }>
-			<ExperimentalBlockEditorProvider value={ blocks }>
-				{ children }
-			</ExperimentalBlockEditorProvider>
-		</div>
-	);
-}
-
-function BlockMoverStory() {
+function BlockMoverStoryHorizontal() {
 	const { updateBlockListSettings } = useDispatch( blockEditorStore );
 
 	useEffect( () => {
 		/**
-		 * This shouldn't be needed but unfortunatley
+		 * This shouldn't be needed but unfortunately
 		 * the layout orientation is not declarative, we need
-		 *  to render the blocks to update the block settings in the state.
+		 * to render the blocks to update the block settings in the state.
 		 */
 		updateBlockListSettings( blocks[ 1 ].clientId, {
 			orientation: 'horizontal',
 		} );
 	}, [] );
 
 	return (
-		<div>
-			<p>The mover by default is vertical</p>
-			<Toolbar label="Block Mover">
-				<BlockMover
-					clientIds={
-						blocks.length
-							? [ blocks[ 0 ].innerBlocks[ 1 ].clientId ]
-							: []
-					}
-				/>
-			</Toolbar>
-
-			<p style={ { marginTop: 36 } }>
-				But it can also accommodate horizontal blocks.
-			</p>
-			<Toolbar label="Block Mover">
-				<BlockMover
-					clientIds={
-						blocks.length
-							? [ blocks[ 1 ].innerBlocks[ 1 ].clientId ]
-							: []
-					}
-				/>
-			</Toolbar>
-
-			<p style={ { marginTop: 36 } }>We can also hide the drag handle.</p>
-			<Toolbar label="Block Mover">
-				<BlockMover
-					clientIds={
-						blocks.length
-							? [ blocks[ 1 ].innerBlocks[ 0 ].clientId ]
-							: []
-					}
-					hideDragHandle
-				/>
-			</Toolbar>
-		</div>
+		<BlockMover
+			clientIds={
+				blocks.length ? [ blocks[ 1 ].innerBlocks[ 1 ].clientId ] : []
+			}
+		/>
 	);
 }
 
-export default {
+/**
+ * BlockMover component allows moving blocks inside the editor using up and down buttons.
+ */
+const meta = {
 	title: 'BlockEditor/BlockMover',
+	component: BlockMover,
+	parameters: {
+		docs: { canvas: { sourceState: 'shown' } },
+	},
+	decorators: [
+		( Story ) => (
+			<ExperimentalBlockEditorProvider value={ blocks }>
+				<Toolbar label="Block Mover">
+					<Story />
+				</Toolbar>
+			</ExperimentalBlockEditorProvider>
+		),
+	],
+	argTypes: {
+		clientIds: {
+			control: {
+				type: 'array',
+			},
+			description: 'The client IDs of the blocks to move.',
+		},
+		hideDragHandle: {
+			control: {
+				type: 'boolean',
+			},
+			description: 'If this property is true, the drag handle is hidden.',
+		},
+	},
+};
+export default meta;
+
+const Template = ( props ) => {
+	return (
+		<BlockMover
+			{ ...props }
+			clientIds={
+				blocks.length ? [ blocks[ 1 ].innerBlocks[ 1 ].clientId ] : []
+			}
+		/>
+	);
+};
+
+export const Default = Template.bind( {} );
+Default.args = {
+	clientIds: [
+		blocks.length ? [ blocks[ 0 ].innerBlocks[ 1 ].clientId ] : [],
+	],
+};
+
+/**
+ * This story shows the block mover with horizontal orientation.
+ * It is necessary to render the blocks to update the block settings in the state.
+ */
+export const Horizontal = ( props ) => {
+	return <BlockMoverStoryHorizontal { ...props } />;
+};
+Horizontal.args = {
+	clientIds: [
+		blocks.length ? [ blocks[ 1 ].innerBlocks[ 1 ].clientId ] : [],
+	],
+};
+Horizontal.parameters = {
+	docs: { canvas: { sourceState: 'hidden' } },
 };
 
-export const _default = () => {
+/**
+ * You can hide the drag handle by `hideDragHandle` attribute.
+ */
+export const HideDragHandle = ( props ) => {
 	return (
-		<Provider>
-			<BlockMoverStory />
-		</Provider>
+		<BlockMover
+			{ ...props }
+			clientIds={
+				blocks.length ? [ blocks[ 1 ].innerBlocks[ 1 ].clientId ] : []
+			}
+			hideDragHandle
+		/>
 	);
 };
+HideDragHandle.args = {
+	...Default.args,
+	hideDragHandle: true,
+};