Storybook: Add Story for MediaReplaceFlow

packages/block-editor/src/components/media-replace-flow/index.js

@@ -39,6 +39,51 @@ import { store as blockEditorStore } from '../../store';
 const noop = () => {};
 let uniqueId = 0;
 
+/**
+ * A component that implements a replacement flow for various media objects.
+ *
+ * @example
+ * ```jsx
+ * function Example() {
+ *   const [ mediaURL, setMediaURL ] = useState( 'https://example.media' );
+ *
+ *   return (
+ *     <BlockControls>
+ *       <MediaReplaceFlow
+ *         allowedTypes={ [ 'png' ] }
+ *         accept="image/*"
+ *         mediaURL={ mediaURL }
+ *         onSelectURL={ setMediaURL }
+ *       />
+ *     </BlockControls>
+ *   );
+ * }
+ * ```
+ *
+ * @param {Object}   props                       The component props.
+ * @param {string}   props.mediaURL              The URL of the media.
+ * @param {number}   props.mediaId               The Id of the attachment post type for the current media.
+ * @param {Array}    props.mediaIds              The Ids of the attachments post type for the current media.
+ * @param {Array}    props.allowedTypes          A list of media types allowed to replace the current media.
+ * @param {string}   props.accept                The mime type of the media.
+ * @param {Function} props.onError               Callback called when an upload error happens and receives an error message as an argument.
+ * @param {Function} props.onSelect              Callback used when media is replaced from the Media Library or when a new media is uploaded. It is called with one argument `media` which is an object with all the media details.
+ * @param {Function} props.onSelectURL           Callback used when media URL is selected.
+ * @param {Function} props.onReset               Callback used when the media should be reset.
+ * @param {Function} props.onToggleFeaturedImage Callback used when the featured image should be toggled.
+ * @param {boolean}  props.useFeaturedImage      Whether the featured image is currently used.
+ * @param {Function} props.onFilesUpload         Callback called before to start to upload the files. It receives an array with the files to upload before to the final process.
+ * @param {string}   props.name                  A `string` value will be used as the label of the replace button. It can also accept `Phrasing content` elements(ex. `span`).
+ * @param {Function} props.createNotice          Creates a media replace notice.
+ * @param {Function} props.removeNotice          Removes a media replace notice.
+ * @param {Element}  props.children              If passed, children are rendered inside the dropdown.
+ * @param {boolean}  props.multiple              If multiple is true, the user can select multiple images from the media library.
+ * @param {boolean}  props.addToGallery          If true, the user can add the selected images to the gallery.
+ * @param {boolean}  props.handleUpload          Whether the component should handle the upload process.
+ * @param {Object}   props.popoverProps          The props to be passed to the `Popover` component.
+ *
+ * @return {Element} The component to be rendered.
+ */
 const MediaReplaceFlow = ( {
 	mediaURL,
 	mediaId,

packages/block-editor/src/components/media-replace-flow/stories/index.story.js

@@ -0,0 +1,115 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import MediaReplaceFlow from '../';
+import { useState } from '@wordpress/element';
+
+export default {
+	title: 'BlockEditor/MediaReplaceFlow',
+	component: MediaReplaceFlow,
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'A component that implements a replacement flow for various media objects.',
+			},
+		},
+	},
+	argTypes: {
+		mediaURL: {
+			control: 'text',
+			description: 'The URL of the media.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		mediaId: {
+			control: 'number',
+			description:
+				'The Id of the attachment post type for the current media.',
+			table: {
+				type: { summary: 'int' },
+			},
+		},
+		allowedTypes: {
+			control: 'array',
+			description:
+				'A list of media types allowed to replace the current media.',
+			table: {
+				type: { summary: 'array' },
+			},
+		},
+		accept: {
+			control: 'text',
+			description: 'The mime type of the media.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		onSelect: {
+			control: { type: 'function' },
+			description: __( 'Callback when media is selected.' ),
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+		onSelectURL: {
+			control: { type: 'function' },
+			description: __( 'Callback when media URL is selected.' ),
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+		onError: {
+			control: { type: 'function' },
+			description: __( 'Callback when an error happens.' ),
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+		name: {
+			control: 'text',
+			description: 'The label of the replace button.',
+			table: {
+				type: { summary: 'string' },
+			},
+		},
+		createNotice: {
+			control: { type: 'function' },
+			description: __( 'Callback to create a notice.' ),
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+		removeNotice: {
+			control: { type: 'function' },
+			description: __( 'Callback to remove a notice.' ),
+			table: {
+				type: { summary: 'function' },
+			},
+		},
+	},
+};
+
+export const Default = {
+	args: {
+		allowedTypes: [ 'png' ],
+		accept: 'image/*',
+	},
+	render: function Template( args ) {
+		const [ mediaURL, setMediaURL ] = useState( 'https://example.media' );
+		return (
+			<MediaReplaceFlow
+				{ ...args }
+				mediaURL={ mediaURL }
+				onSelectURL={ setMediaURL }
+			/>
+		);
+	},
+};