@wordpress/editor 13.32.0 → 13.34.0

package/src/components/more-menu/index.js

@@ -0,0 +1,158 @@
+/**
+ * WordPress dependencies
+ */
+import { __, _x } from '@wordpress/i18n';
+import { useSelect, useDispatch } from '@wordpress/data';
+import { displayShortcut } from '@wordpress/keycodes';
+import { external, moreVertical } from '@wordpress/icons';
+import {
+	MenuGroup,
+	MenuItem,
+	VisuallyHidden,
+	DropdownMenu,
+} from '@wordpress/components';
+import {
+	PreferenceToggleMenuItem,
+	store as preferencesStore,
+} from '@wordpress/preferences';
+import { store as interfaceStore, ActionItem } from '@wordpress/interface';
+
+/**
+ * Internal dependencies
+ */
+import CopyContentMenuItem from './copy-content-menu-item';
+import ModeSwitcher from '../mode-switcher';
+import ToolsMoreMenuGroup from './tools-more-menu-group';
+import ViewMoreMenuGroup from './view-more-menu-group';
+import { store as editorStore } from '../../store';
+
+export default function MoreMenu() {
+	const { openModal } = useDispatch( interfaceStore );
+	const { set: setPreference } = useDispatch( preferencesStore );
+	const { toggleDistractionFree } = useDispatch( editorStore );
+	const showIconLabels = useSelect(
+		( select ) =>
+			select( preferencesStore ).get( 'core', 'showIconLabels' ),
+		[]
+	);
+	const turnOffDistractionFree = () => {
+		setPreference( 'core', 'distractionFree', false );
+	};
+
+	return (
+		<>
+			<DropdownMenu
+				icon={ moreVertical }
+				label={ __( 'Options' ) }
+				popoverProps={ {
+					placement: 'bottom-end',
+					className: 'more-menu-dropdown__content',
+				} }
+				toggleProps={ {
+					showTooltip: ! showIconLabels,
+					...( showIconLabels && { variant: 'tertiary' } ),
+					tooltipPosition: 'bottom',
+					size: 'compact',
+				} }
+			>
+				{ ( { onClose } ) => (
+					<>
+						<MenuGroup label={ _x( 'View', 'noun' ) }>
+							<PreferenceToggleMenuItem
+								scope="core"
+								name="fixedToolbar"
+								onToggle={ turnOffDistractionFree }
+								label={ __( 'Top toolbar' ) }
+								info={ __(
+									'Access all block and document tools in a single place'
+								) }
+								messageActivated={ __(
+									'Top toolbar activated'
+								) }
+								messageDeactivated={ __(
+									'Top toolbar deactivated'
+								) }
+							/>
+							<PreferenceToggleMenuItem
+								scope="core"
+								name="distractionFree"
+								label={ __( 'Distraction free' ) }
+								info={ __( 'Write with calmness' ) }
+								handleToggling={ false }
+								onToggle={ toggleDistractionFree }
+								messageActivated={ __(
+									'Distraction free mode activated'
+								) }
+								messageDeactivated={ __(
+									'Distraction free mode deactivated'
+								) }
+								shortcut={ displayShortcut.primaryShift(
+									'\\'
+								) }
+							/>
+							<PreferenceToggleMenuItem
+								scope="core"
+								name="focusMode"
+								label={ __( 'Spotlight mode' ) }
+								info={ __( 'Focus on one block at a time' ) }
+								messageActivated={ __(
+									'Spotlight mode activated'
+								) }
+								messageDeactivated={ __(
+									'Spotlight mode deactivated'
+								) }
+							/>
+							<ViewMoreMenuGroup.Slot fillProps={ { onClose } } />
+						</MenuGroup>
+						<ModeSwitcher />
+						<ActionItem.Slot
+							name="core/plugin-more-menu"
+							label={ __( 'Plugins' ) }
+							as={ MenuGroup }
+							fillProps={ { onClick: onClose } }
+						/>
+						<MenuGroup label={ __( 'Tools' ) }>
+							<MenuItem
+								onClick={ () =>
+									openModal( 'editor/keyboard-shortcut-help' )
+								}
+								shortcut={ displayShortcut.access( 'h' ) }
+							>
+								{ __( 'Keyboard shortcuts' ) }
+							</MenuItem>
+							<CopyContentMenuItem />
+							<MenuItem
+								icon={ external }
+								href={ __(
+									'https://wordpress.org/documentation/article/wordpress-block-editor/'
+								) }
+								target="_blank"
+								rel="noopener noreferrer"
+							>
+								{ __( 'Help' ) }
+								<VisuallyHidden as="span">
+									{
+										/* translators: accessibility text */
+										__( '(opens in a new tab)' )
+									}
+								</VisuallyHidden>
+							</MenuItem>
+							<ToolsMoreMenuGroup.Slot
+								fillProps={ { onClose } }
+							/>
+						</MenuGroup>
+						<MenuGroup>
+							<MenuItem
+								onClick={ () =>
+									openModal( 'editor/preferences' )
+								}
+							>
+								{ __( 'Preferences' ) }
+							</MenuItem>
+						</MenuGroup>
+					</>
+				) }
+			</DropdownMenu>
+		</>
+	);
+}

package/src/components/more-menu/tools-more-menu-group.js

@@ -0,0 +1,11 @@
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill } from '@wordpress/components';
+
+const { Fill: ToolsMoreMenuGroup, Slot } =
+	createSlotFill( 'ToolsMoreMenuGroup' );
+
+ToolsMoreMenuGroup.Slot = ( { fillProps } ) => <Slot fillProps={ fillProps } />;
+
+export default ToolsMoreMenuGroup;

package/src/components/more-menu/view-more-menu-group.js

@@ -0,0 +1,13 @@
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill } from '@wordpress/components';
+import { Platform } from '@wordpress/element';
+
+const { Fill: ViewMoreMenuGroup, Slot } = createSlotFill(
+	Platform.OS === 'web' ? Symbol( 'ViewMoreMenuGroup' ) : 'ViewMoreMenuGroup'
+);
+
+ViewMoreMenuGroup.Slot = ( { fillProps } ) => <Slot fillProps={ fillProps } />;
+
+export default ViewMoreMenuGroup;

package/src/components/page-attributes/check.js

@@ -9,6 +9,14 @@ import { store as coreStore } from '@wordpress/core-data';
  */
 import { store as editorStore } from '../../store';
 
+/**
+ * Wrapper component that renders its children only if the post type supports page attributes.
+ *
+ * @param {Object}  props          - The component props.
+ * @param {Element} props.children - The child components to render.
+ *
+ * @return {Component|null} The rendered child components or null if page attributes are not supported.
+ */
 export function PageAttributesCheck( { children } ) {
 	const supportsPageAttributes = useSelect( ( select ) => {
 		const { getEditedPostAttribute } = select( editorStore );

package/src/components/page-attributes/order.js

@@ -53,6 +53,12 @@ function PageAttributesOrder() {
 	);
 }
 
+/**
+ * Renders the Page Attributes Order component. A number input in an editor interface
+ * for setting the order of a given page.
+ *
+ * @return {Component} The component to be rendered.
+ */
 export default function PageAttributesOrderWithChecks() {
 	return (
 		<PostTypeSupportCheck supportKeys="page-attributes">

package/src/components/page-attributes/panel.js

@@ -17,7 +17,7 @@ import PageAttributesParent from './parent';
 
 const PANEL_NAME = 'page-attributes';
 
-export function PageAttributesPanel() {
+function AttributesPanel() {
 	const { isEnabled, isOpened, postType } = useSelect( ( select ) => {
 		const {
 			getEditedPostAttribute,
@@ -38,25 +38,29 @@ export function PageAttributesPanel() {
 		return null;
 	}
 
-	const onTogglePanel = ( ...args ) =>
-		toggleEditorPanelOpened( PANEL_NAME, ...args );
+	return (
+		<PanelBody
+			title={ postType?.labels?.attributes ?? __( 'Page attributes' ) }
+			opened={ isOpened }
+			onToggle={ () => toggleEditorPanelOpened( PANEL_NAME ) }
+		>
+			<PageAttributesParent />
+			<PanelRow>
+				<PageAttributesOrder />
+			</PanelRow>
+		</PanelBody>
+	);
+}
 
+/**
+ * Renders the Page Attributes Panel component.
+ *
+ * @return {Component} The component to be rendered.
+ */
+export default function PageAttributesPanel() {
 	return (
 		<PageAttributesCheck>
-			<PanelBody
-				title={
-					postType?.labels?.attributes ?? __( 'Page attributes' )
-				}
-				opened={ isOpened }
-				onToggle={ onTogglePanel }
-			>
-				<PageAttributesParent />
-				<PanelRow>
-					<PageAttributesOrder />
-				</PanelRow>
-			</PanelBody>
+			<AttributesPanel />
 		</PageAttributesCheck>
 	);
 }
-
-export default PageAttributesPanel;

package/src/components/page-attributes/parent.js

@@ -40,6 +40,12 @@ export const getItemPriority = ( name, searchValue ) => {
 	return Infinity;
 };
 
+/**
+ * Renders the Page Attributes Parent component. A dropdown menu in an editor interface
+ * for selecting the parent page of a given page.
+ *
+ * @return {Component|null} The component to be rendered. Return null if post type is not hierarchical.
+ */
 export function PageAttributesParent() {
 	const { editPost } = useDispatch( editorStore );
 	const [ fieldValue, setFieldValue ] = useState( false );

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

@@ -0,0 +1,73 @@
+/**
+ * WordPress dependencies
+ */
+import { compose } from '@wordpress/compose';
+import { MenuItem } from '@wordpress/components';
+import { withPluginContext } from '@wordpress/plugins';
+import { ActionItem } from '@wordpress/interface';
+
+/**
+ * Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to as a button or link depending on the props provided.
+ * The text within the component appears as the menu item label.
+ *
+ * @param {Object}                props                                 Component properties.
+ * @param {string}                [props.href]                          When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor.
+ * @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.
+ * @param {Function}              [props.onClick=noop]                  The callback function to be executed when the user clicks the menu item.
+ * @param {...*}                  [props.other]                         Any additional props are passed through to the underlying [Button](/packages/components/src/button/README.md) component.
+ *
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var __ = wp.i18n.__;
+ * var PluginMoreMenuItem = wp.editor.PluginMoreMenuItem;
+ * var moreIcon = wp.element.createElement( 'svg' ); //... svg element.
+ *
+ * function onButtonClick() {
+ * 	alert( 'Button clicked.' );
+ * }
+ *
+ * function MyButtonMoreMenuItem() {
+ * 	return wp.element.createElement(
+ * 		PluginMoreMenuItem,
+ * 		{
+ * 			icon: moreIcon,
+ * 			onClick: onButtonClick,
+ * 		},
+ * 		__( 'My button title' )
+ * 	);
+ * }
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // Using ESNext syntax
+ * import { __ } from '@wordpress/i18n';
+ * import { PluginMoreMenuItem } from '@wordpress/editor';
+ * import { more } from '@wordpress/icons';
+ *
+ * function onButtonClick() {
+ * 	alert( 'Button clicked.' );
+ * }
+ *
+ * const MyButtonMoreMenuItem = () => (
+ * 	<PluginMoreMenuItem
+ * 		icon={ more }
+ * 		onClick={ onButtonClick }
+ * 	>
+ * 		{ __( 'My button title' ) }
+ * 	</PluginMoreMenuItem>
+ * );
+ * ```
+ *
+ * @return {Component} The component to be rendered.
+ */
+export default compose(
+	withPluginContext( ( context, ownProps ) => {
+		return {
+			as: ownProps.as ?? MenuItem,
+			icon: ownProps.icon || context.icon,
+			name: 'core/plugin-more-menu',
+		};
+	} )
+)( ActionItem );

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

@@ -21,7 +21,7 @@ const { Fill, Slot } = createSlotFill( 'PluginPostPublishPanel' );
  * ```jsx
  * // Using ESNext syntax
  * import { __ } from '@wordpress/i18n';
- * import { PluginPostPublishPanel } from '@wordpress/edit-post';
+ * import { PluginPostPublishPanel } from '@wordpress/editor';
  *
  * const MyPluginPostPublishPanel = () => (
  * 	<PluginPostPublishPanel

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

@@ -24,7 +24,7 @@ const { Fill, Slot } = createSlotFill( 'PluginPrePublishPanel' );
  * ```jsx
  * // Using ESNext syntax
  * import { __ } from '@wordpress/i18n';
- * import { PluginPrePublishPanel } from '@wordpress/edit-post';
+ * import { PluginPrePublishPanel } from '@wordpress/editor';
  *
  * const MyPluginPrePublishPanel = () => (
  * 	<PluginPrePublishPanel

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/editor';
+ * 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 }
+		/>
+	);
+}