Cover Block: Normalize the block toolbar

packages/block-editor/src/components/block-alignment-matrix-control/README.md

@@ -0,0 +1,63 @@
+# Alignment Matrix Control
+
+The alignment matrix control allows users to quickly adjust inner block alignment; this is in contrast to the alignment toolbar that aligns the frame block.
+
+![Button components](https://i.imgur.com/PxYkgL5.png)
+
+## Table of contents
+
+-   [Alignment Matrix Control](#alignment-matrix-control)
+    -   [Table of contents](#table-of-contents)
+    -   [Design guidelines](#design-guidelines)
+        -   [Usage](#usage)
+    -   [Development guidelines](#development-guidelines)
+        -   [Usage](#usage-1)
+        -   [Props](#props)
+
+## Design guidelines
+
+### Usage
+
+The alignment matrix is a specialized tool, and it's used in the cover block.
+
+![Cover](https://i.imgur.com/nJjqen8.png)
+
+As an example, here's the matrix alignment tool in action.
+
+![center](https://i.imgur.com/0Ce1fZm.png)
+
+![rop_right](https://i.imgur.com/yGGf6IP.png)
+
+## Development guidelines
+
+### Usage
+
+```jsx
+// This is a paraphrased example from the cover block
+import {
+    BlockControls,
+    __experimentalBlockAlignmentMatrixControl as BlockAlignmentMatrixControl
+} from "@wordpress/block-editor";
+
+const controls = (
+  <>
+    <BlockControls>
+      <BlockAlignmentMatrixControl
+        label={ __( 'Change content position' ) }
+        value={ contentPosition }
+        onChange={ ( nextPosition ) =>
+          setAttributes( { contentPosition: nextPosition } )
+        }
+      />
+    </BlockControls>
+  </>
+}
+```
+
+### Props
+
+| Name       | Type       | Default                   | Description                                                                                                                              |
+| ---------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`    | `string`   | `Change matrix alignment` | concise description of tool's functionality.                                                                                             |
+| `onChange` | `function` | `noop`                    | the function to execute upon a user's change of the matrix state                                                                         |
+| `value`    | `string`   | `center`                  | describes the content alignment location and can be `top`, `right`, `bottom`, `left`, `topRight`, `bottomRight`, `bottomLeft`, `topLeft` |

packages/block-editor/src/components/block-alignment-matrix-toolbar/index.js → packages/block-editor/src/components/block-alignment-matrix-control/index.js

@@ -10,11 +10,10 @@ import { DOWN } from '@wordpress/keycodes';
 import {
 	ToolbarButton,
 	Dropdown,
-	ToolbarGroup,
 	__experimentalAlignmentMatrixControl as AlignmentMatrixControl,
 } from '@wordpress/components';
 
-export function BlockAlignmentMatrixToolbar( props ) {
+function BlockAlignmentMatrixControl( props ) {
 	const {
 		label = __( 'Change matrix alignment' ),
 		onChange = noop,
@@ -23,7 +22,7 @@ export function BlockAlignmentMatrixToolbar( props ) {
 	} = props;
 
 	const icon = <AlignmentMatrixControl.Icon value={ value } />;
-	const className = 'block-editor-block-alignment-matrix-toolbar';
+	const className = 'block-editor-block-alignment-matrix-control';
 	const popoverClassName = `${ className }__popover`;
 	const isAlternate = true;
 
@@ -42,18 +41,16 @@ export function BlockAlignmentMatrixToolbar( props ) {
 				};
 
 				return (
-					<ToolbarGroup>
-						<ToolbarButton
-							onClick={ onToggle }
-							aria-haspopup="true"
-							aria-expanded={ isOpen }
-							onKeyDown={ openOnArrowDown }
-							label={ label }
-							icon={ icon }
-							showTooltip
-							disabled={ isDisabled }
-						/>
-					</ToolbarGroup>
+					<ToolbarButton
+						onClick={ onToggle }
+						aria-haspopup="true"
+						aria-expanded={ isOpen }
+						onKeyDown={ openOnArrowDown }
+						label={ label }
+						icon={ icon }
+						showTooltip
+						disabled={ isDisabled }
+					/>
 				);
 			} }
 			renderContent={ () => (
@@ -67,4 +64,4 @@ export function BlockAlignmentMatrixToolbar( props ) {
 	);
 }
 
-export default BlockAlignmentMatrixToolbar;
+export default BlockAlignmentMatrixControl;

packages/block-editor/src/components/block-alignment-matrix-toolbar/style.scss → packages/block-editor/src/components/block-alignment-matrix-control/style.scss

@@ -1,4 +1,4 @@
-.block-editor-block-alignment-matrix-toolbar__popover {
+.block-editor-block-alignment-matrix-control__popover {
 	.components-popover__content {
 		min-width: 0;
 		width: auto;
@@ -7,5 +7,4 @@
 			padding: $grid-unit;
 		}
 	}
-
 }

packages/block-editor/src/components/block-controls/index.js

@@ -11,24 +11,69 @@ import {
 	__experimentalToolbarContext as ToolbarContext,
 	createSlotFill,
 	ToolbarGroup,
+	__experimentalUseSlot as useSlot,
 } from '@wordpress/components';
 
 /**
  * Internal dependencies
  */
 import useDisplayBlockControls from '../use-display-block-controls';
 
-const { Fill, Slot } = createSlotFill( 'BlockControls' );
+const BlockControlsDefault = createSlotFill( 'BlockControls' );
+const BlockControlsBlock = createSlotFill( 'BlockFormatControlsBlock' );
+const BlockControlsInline = createSlotFill( 'BlockFormatControls' );
+const BlockControlsOther = createSlotFill( 'BlockControlsOther' );
 
-function BlockControlsSlot( props ) {
+const segments = {
+	default: BlockControlsDefault,
+	block: BlockControlsBlock,
+	inline: BlockControlsInline,
+	other: BlockControlsOther,
+};
+
+const slotNames = {
+	default: 'BlockControls',
+	block: 'BlockFormatControlsBlock',
+	inline: 'BlockFormatControls',
+	other: 'BlockControlsOther',
+};
+
+function BlockControlsSlot( { segment = 'default', ...props } ) {
 	const accessibleToolbarState = useContext( ToolbarContext );
-	return <Slot { ...props } fillProps={ accessibleToolbarState } />;
+	const Slot = segments[ segment ].Slot;
+	const slot = useSlot( slotNames[ segment ] );
+	const hasFills = Boolean( slot.fills && slot.fills.length );
+
+	if ( ! hasFills ) {
+		return null;
+	}
+
+	if ( segment === 'default' ) {
+		return (
+			<Slot
+				{ ...props }
+				bubblesVirtually
+				fillProps={ accessibleToolbarState }
+			/>
+		);
+	}
+
+	return (
+		<ToolbarGroup>
+			<Slot
+				{ ...props }
+				bubblesVirtually
+				fillProps={ accessibleToolbarState }
+			/>
+		</ToolbarGroup>
+	);
 }
 
-function BlockControlsFill( { controls, children } ) {
+function BlockControlsFill( { segment = 'default', controls, children } ) {
 	if ( ! useDisplayBlockControls() ) {
 		return null;
 	}
+	const Fill = segments[ segment ].Fill;
 
 	return (
 		<Fill>
@@ -39,7 +84,9 @@ function BlockControlsFill( { controls, children } ) {
 				const value = ! isEmpty( fillProps ) ? fillProps : null;
 				return (
 					<ToolbarContext.Provider value={ value }>
-						<ToolbarGroup controls={ controls } />
+						{ segment === 'default' && (
+							<ToolbarGroup controls={ controls } />
+						) }
 						{ children }
 					</ToolbarContext.Provider>
 				);
@@ -52,4 +99,12 @@ const BlockControls = BlockControlsFill;
 
 BlockControls.Slot = BlockControlsSlot;
 
+// This is just here for backward compatibility
+export const BlockFormatControls = ( props ) => {
+	return <BlockControlsFill segment="inline" { ...props } />;
+};
+BlockFormatControls.Slot = ( props ) => {
+	return <BlockControlsSlot segment="inline" { ...props } />;
+};
+
 export default BlockControls;

packages/block-editor/src/components/block-full-height-alignment-toolbar/README.md → packages/block-editor/src/components/block-full-height-alignment-control/README.md

@@ -1,3 +1,3 @@
-# Full Height Toolbar Toolbar
+# Full Height Toolbar Control
 
 Unlike the block alignment options, `Full Height Alignment` can be applied to a block in an independent way. But also, it works very well together with these block alignment options, where the combination empowers the design-layout capability.