@wordpress/editor 13.31.0 → 13.33.0

package/src/components/plugin-post-status-info/index.js

@@ -0,0 +1,63 @@
+/**
+ * Defines as extensibility slot for the Summary panel.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill, PanelRow } from '@wordpress/components';
+
+const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' );
+
+/**
+ * Renders a row in the Summary panel of the Document sidebar.
+ * It should be noted that this is named and implemented around the function it serves
+ * and not its location, which may change in future iterations.
+ *
+ * @param {Object}  props             Component properties.
+ * @param {string}  [props.className] An optional class name added to the row.
+ * @param {Element} props.children    Children to be rendered.
+ *
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var __ = wp.i18n.__;
+ * var PluginPostStatusInfo = wp.editor.PluginPostStatusInfo;
+ *
+ * function MyPluginPostStatusInfo() {
+ * 	return React.createElement(
+ * 		PluginPostStatusInfo,
+ * 		{
+ * 			className: 'my-plugin-post-status-info',
+ * 		},
+ * 		__( 'My post status info' )
+ * 	)
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // Using ESNext syntax
+ * import { __ } from '@wordpress/i18n';
+ * import { PluginPostStatusInfo } from '@wordpress/editor';
+ *
+ * const MyPluginPostStatusInfo = () => (
+ * 	<PluginPostStatusInfo
+ * 		className="my-plugin-post-status-info"
+ * 	>
+ * 		{ __( 'My post status info' ) }
+ * 	</PluginPostStatusInfo>
+ * );
+ * ```
+ *
+ * @return {Component} The component to be rendered.
+ */
+const PluginPostStatusInfo = ( { children, className } ) => (
+	<Fill>
+		<PanelRow className={ className }>{ children }</PanelRow>
+	</Fill>
+);
+
+PluginPostStatusInfo.Slot = Slot;
+
+export default PluginPostStatusInfo;

package/src/components/plugin-pre-publish-panel/index.js

@@ -0,0 +1,67 @@
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill, PanelBody } from '@wordpress/components';
+import { usePluginContext } from '@wordpress/plugins';
+
+const { Fill, Slot } = createSlotFill( 'PluginPrePublishPanel' );
+
+/**
+ * Renders provided content to the pre-publish side panel in the publish flow
+ * (side panel that opens when a user first pushes "Publish" from the main editor).
+ *
+ * @param {Object}                props                                 Component props.
+ * @param {string}                [props.className]                     An optional class name added to the panel.
+ * @param {string}                [props.title]                         Title displayed at the top of the panel.
+ * @param {boolean}               [props.initialOpen=false]             Whether to have the panel initially opened.
+ *                                                                      When no title is provided it is always opened.
+ * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/)
+ *                                                                      icon slug string, or an SVG WP element, to be rendered when
+ *                                                                      the sidebar is pinned to toolbar.
+ * @param {Element}               props.children                        Children to be rendered
+ *
+ * @example
+ * ```jsx
+ * // Using ESNext syntax
+ * import { __ } from '@wordpress/i18n';
+ * import { PluginPrePublishPanel } from '@wordpress/edit-post';
+ *
+ * const MyPluginPrePublishPanel = () => (
+ * 	<PluginPrePublishPanel
+ * 		className="my-plugin-pre-publish-panel"
+ * 		title={ __( 'My panel title' ) }
+ * 		initialOpen={ true }
+ * 	>
+ * 	    { __( 'My panel content' ) }
+ * 	</PluginPrePublishPanel>
+ * );
+ * ```
+ *
+ * @return {Component} The component to be rendered.
+ */
+const PluginPrePublishPanel = ( {
+	children,
+	className,
+	title,
+	initialOpen = false,
+	icon,
+} ) => {
+	const { icon: pluginIcon } = usePluginContext();
+
+	return (
+		<Fill>
+			<PanelBody
+				className={ className }
+				initialOpen={ initialOpen || ! title }
+				title={ title }
+				icon={ icon ?? pluginIcon }
+			>
+				{ children }
+			</PanelBody>
+		</Fill>
+	);
+};
+
+PluginPrePublishPanel.Slot = Slot;
+
+export default PluginPrePublishPanel;

package/src/components/plugin-pre-publish-panel/test/index.js

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { SlotFillProvider } from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import PluginPrePublishPanel from '../';
+
+describe( 'PluginPrePublishPanel', () => {
+	test( 'renders fill properly', () => {
+		render(
+			<SlotFillProvider>
+				<PluginPrePublishPanel
+					className="my-plugin-pre-publish-panel"
+					title="My panel title"
+					initialOpen
+				>
+					My panel content
+				</PluginPrePublishPanel>
+				<PluginPrePublishPanel.Slot />
+			</SlotFillProvider>
+		);
+
+		expect( screen.getByText( 'My panel title' ) ).toBeVisible();
+	} );
+} );

package/src/components/plugin-sidebar/index.js

@@ -0,0 +1,98 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { __ } from '@wordpress/i18n';
+import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
+import { ComplementaryArea } from '@wordpress/interface';
+
+/**
+ * Internal dependencies
+ */
+import { store as editorStore } from '../../store';
+
+/**
+ * Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar.
+ * It also automatically renders a corresponding `PluginSidebarMenuItem` component when `isPinnable` flag is set to `true`.
+ * If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API:
+ *
+ * ```js
+ * wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/sidebar-name' );
+ * ```
+ *
+ * @see PluginSidebarMoreMenuItem
+ *
+ * @param {Object}                props                                 Element props.
+ * @param {string}                props.name                            A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin.
+ * @param {string}                [props.className]                     An optional class name added to the sidebar body.
+ * @param {string}                props.title                           Title displayed at the top of the sidebar.
+ * @param {boolean}               [props.isPinnable=true]               Whether to allow to pin sidebar to the toolbar. When set to `true` it also automatically renders a corresponding menu item.
+ * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar.
+ *
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var __ = wp.i18n.__;
+ * var el = React.createElement;
+ * var PanelBody = wp.components.PanelBody;
+ * var PluginSidebar = wp.editor.PluginSidebar;
+ * var moreIcon = React.createElement( 'svg' ); //... svg element.
+ *
+ * function MyPluginSidebar() {
+ * 	return el(
+ * 			PluginSidebar,
+ * 			{
+ * 				name: 'my-sidebar',
+ * 				title: 'My sidebar title',
+ * 				icon: moreIcon,
+ * 			},
+ * 			el(
+ * 				PanelBody,
+ * 				{},
+ * 				__( 'My sidebar content' )
+ * 			)
+ * 	);
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // Using ESNext syntax
+ * import { __ } from '@wordpress/i18n';
+ * import { PanelBody } from '@wordpress/components';
+ * import { PluginSidebar } from '@wordpress/edit-post';
+ * import { more } from '@wordpress/icons';
+ *
+ * const MyPluginSidebar = () => (
+ * 	<PluginSidebar
+ * 		name="my-sidebar"
+ * 		title="My sidebar title"
+ * 		icon={ more }
+ * 	>
+ * 		<PanelBody>
+ * 			{ __( 'My sidebar content' ) }
+ * 		</PanelBody>
+ * 	</PluginSidebar>
+ * );
+ * ```
+ */
+export default function PluginSidebar( { className, ...props } ) {
+	const { postTitle, shortcut } = useSelect( ( select ) => {
+		return {
+			postTitle: select( editorStore ).getEditedPostAttribute( 'title' ),
+			shortcut: select(
+				keyboardShortcutsStore
+			).getShortcutRepresentation( 'core/editor/toggle-sidebar' ),
+		};
+	}, [] );
+	return (
+		<ComplementaryArea
+			panelClassName={ className }
+			className="editor-sidebar"
+			smallScreenTitle={ postTitle || __( '(no title)' ) }
+			scope="core"
+			toggleShortcut={ shortcut }
+			{ ...props }
+		/>
+	);
+}

package/src/components/plugin-sidebar-more-menu-item/index.js

@@ -0,0 +1,64 @@
+/**
+ * WordPress dependencies
+ */
+import { ComplementaryAreaMoreMenuItem } from '@wordpress/interface';
+
+/**
+ * Renders a menu item in `Plugins` group in `More Menu` drop down,
+ * and can be used to activate the corresponding `PluginSidebar` component.
+ * The text within the component appears as the menu item label.
+ *
+ * @param {Object}                props                                 Component props.
+ * @param {string}                props.target                          A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar.
+ * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label.
+ *
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var __ = wp.i18n.__;
+ * var PluginSidebarMoreMenuItem = wp.editor.PluginSidebarMoreMenuItem;
+ * var moreIcon = React.createElement( 'svg' ); //... svg element.
+ *
+ * function MySidebarMoreMenuItem() {
+ * 	return React.createElement(
+ * 		PluginSidebarMoreMenuItem,
+ * 		{
+ * 			target: 'my-sidebar',
+ * 			icon: moreIcon,
+ * 		},
+ * 		__( 'My sidebar title' )
+ * 	)
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // Using ESNext syntax
+ * import { __ } from '@wordpress/i18n';
+ * import { PluginSidebarMoreMenuItem } from '@wordpress/editor';
+ * import { more } from '@wordpress/icons';
+ *
+ * const MySidebarMoreMenuItem = () => (
+ * 	<PluginSidebarMoreMenuItem
+ * 		target="my-sidebar"
+ * 		icon={ more }
+ * 	>
+ * 		{ __( 'My sidebar title' ) }
+ * 	</PluginSidebarMoreMenuItem>
+ * );
+ * ```
+ *
+ * @return {Component} The component to be rendered.
+ */
+
+export default function PluginSidebarMoreMenuItem( props ) {
+	return (
+		<ComplementaryAreaMoreMenuItem
+			// Menu item is marked with unstable prop for backward compatibility.
+			// @see https://github.com/WordPress/gutenberg/issues/14457
+			__unstableExplicitMenuItem
+			scope="core"
+			{ ...props }
+		/>
+	);
+}