Merge branch 'trunk' into block-editor-handbook-toc

WordPress · JustinyAhin · Mar 9, 2021 · Feb 2, 2021 · Feb 2, 2021 · Feb 2, 2021
commit 011d87c90412bf121fd9c77e73404218cda7337b
@@ -324,7 +324,7 @@ This is currently a work in progress and we recommend reviewing the [block based
 
 ## What are block variations? Are they the same as block styles?
 
-No, block variations are different versions of a single base block, sharing a similar functionality, but with slight differences in their implementation, or settings (attributes, InnerBlocks,etc). Block variations are transparent for users, and once there is a registered block variation, it will appear as a new block. For example, the `embed` block registers different block variations to embed content from specific providers.
+No, [block variations](/docs/designers-developers/developers/block-api/block-variations.md) are different versions of a single base block, sharing a similar functionality, but with slight differences in their implementation, or settings (attributes, InnerBlocks,etc). Block variations are transparent for users, and once there is a registered block variation, it will appear as a new block. For example, the `embed` block registers different block variations to embed content from specific providers.
 
 Meanwhile, [block styles](/docs/reference-guides/filters/block-filters.md#block-style-variations) allow you to provide alternative styles to existing blocks, and they work by adding a className to the block’s wrapper. Once a block has registered block styles, a block style selector will appear in its sidebar so that users can choose among the different registered styles.
 

@@ -224,69 +224,9 @@ example: {
 
 -   **Type:** `Object[]`
 
-Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted.
+Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. See the [Block Variations API](/docs/designers-developers/developers/block-api/block-variations.md) for more details.
 
-By default, all variations will show up in the Inserter in addition to the regular block type item. However, setting the `isDefault` flag for any of the variations listed will override the regular block type in the Inserter.
 
-```js
-variations: [
-    {
-		name: 'wordpress',
-		isDefault: true,
-		title: __( 'WordPress' ),
-		description: __( 'Code is poetry!' ),
-		icon: WordPressIcon,
-		attributes: { service: 'wordpress' },
-	},
-	{
-		name: 'google',
-		title: __( 'Google' ),
-		icon: GoogleIcon,
-		attributes: { service: 'google' },
-	},
-	{
-		name: 'twitter',
-		title: __( 'Twitter' ),
-		icon: TwitterIcon,
-		attributes: { service: 'twitter' },
-		keywords: [ __('tweet') ],
-	},
-],
-```
-
-An object describing a variation defined for the block type can contain the following fields:
-
--   `name` (type `string`) – The unique and machine-readable name.
--   `title` (type `string`) – A human-readable variation title.
--   `description` (optional, type `string`) – A detailed variation description.
--   `category` (optional, type `string`) - A category classification, used in search interfaces to arrange block types by category.
--   `icon` (optional, type `string` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type.
--   `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`.
--   `attributes` (optional, type `Object`) – Values that override block attributes.
--   `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks.
--   `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type.
--   `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options:
-    -   `inserter` - Block Variation is shown on the inserter.
-    -   `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block.
-    -   `transform` - Block Variation will be shown in the component for Block Variations transformations.
--   `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching.
--   `isActive` (optional, type `Function`) - A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value.
-
-It's also possible to override the default block style variation using the `className` attribute when defining block variations.
-
-```js
-variations: [
-	{
-		name: 'blue',
-		title: __( 'Blue Quote' ),
-		isDefault: true,
-		attributes: { color: 'blue', className: 'is-style-blue-quote' },
-		icon: 'format-quote',
-		isActive: ( blockAttributes, variationAttributes ) =>
-			blockAttributes.color === variationAttributes.color
-	},
-],
-```
 
 #### supports (optional)
 

@@ -0,0 +1,94 @@
+# Block Variations
+
+Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality. Each block variation is differentiated from the others by setting some initial attributes or inner blocks. Then at the time when a block is inserted these attributes and/or inner blocks are applied.
+
+A great way to understand this API better is by using the `embed` block as an example. The numerous existing variations for embed (WordPress, Youtube, etc..) share the same functionality for editing, saving, and so on, but their basic difference is the `providerNameSlug` attribute's value, which defines the provider that needs to be used.
+
+By default, all variations will show up in the Inserter in addition to the regular block type item. However, setting the `isDefault` flag for any of the variations listed will override the regular block type in the Inserter.
+
+```js
+variations: [
+    {
+		name: 'wordpress',
+		isDefault: true,
+		title: __( 'WordPress' ),
+		description: __( 'Code is poetry!' ),
+		icon: WordPressIcon,
+		attributes: { providerNameSlug: 'wordpress' },
+	},
+	{
+		name: 'google',
+		title: __( 'Google' ),
+		icon: GoogleIcon,
+		attributes: { providerNameSlug: 'google' },
+	},
+	{
+		name: 'twitter',
+		title: __( 'Twitter' ),
+		icon: TwitterIcon,
+		attributes: { providerNameSlug: 'twitter' },
+		keywords: [ __('tweet') ],
+	},
+],
+```
+
+An object describing a variation defined for the block type can contain the following fields:
+
+-   `name` (type `string`) – The unique and machine-readable name.
+-   `title` (type `string`) – A human-readable variation title.
+-   `description` (optional, type `string`) – A detailed variation description.
+-   `category` (optional, type `string`) - A category classification, used in search interfaces to arrange block types by category.
+-   `icon` (optional, type `string` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type.
+-   `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`.
+-   `attributes` (optional, type `Object`) – Values that override block attributes.
+-   `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks.
+-   `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type.
+-   `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options:
+    -   `inserter` - Block Variation is shown on the inserter.
+    -   `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block.
+    -   `transform` - Block Variation will be shown in the component for Block Variations transformations.
+-   `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching.
+-   `isActive` (optional, type `Function`) - A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value.
+
+The main difference between style variations and block variations is that a style variation just applies a `css class` to the block, so it can be styled in an alternative way. If we want to apply initial attributes or inner blocks, we fall in block variation territory. 
+
+It's also possible to override the default block style variation using the `className` attribute when defining block variations.
+
+```js
+variations: [
+	{
+		name: 'blue',
+		title: __( 'Blue Quote' ),
+		isDefault: true,
+		attributes: { color: 'blue', className: 'is-style-blue-quote' },
+		icon: 'format-quote',
+		isActive: ( blockAttributes, variationAttributes ) =>
+			blockAttributes.color === variationAttributes.color
+	},
+],
+```
+
+It's worth mentioning that setting the `isActive` property can be useful for cases you want to use information from the block variation, after a block's creation. For example, this API is used in `useBlockDisplayInformation` hook to fetch and display proper information on places like the `BlockCard` or `Breadcrumbs` components.
+
+
+Block variations can be declared during a block's registration by providing the `variations` key with a proper array of variations, as defined above. In addition, there are ways to register and unregister a `block variation` for a block, after its registration.
+
+To add a block variation use `wp.blocks.registerBlockVariation()`.
+
+_Example:_
+
+```js
+wp.blocks.registerBlockVariation( 'core/embed', {
+	name: 'custom',
+	attributes: { providerNameSlug: 'custom' }
+} );
+```
+
+
+To remove a block variation use `wp.blocks.unregisterBlockVariation()`.
+
+_Example:_
+
+```js
+wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' );
+```
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/block-library/src/post-hierarchical-terms/variations.js b/packages/block-library/src/post-hierarchical-terms/variations.js
@@ -7,9 +7,11 @@ const variations = [
 	{
 		name: 'category',
 		title: __( 'Post Categories' ),
+		description: __( "Display a post's categories." ),
 		icon: 'category',
 		isDefault: true,
 		attributes: { term: 'category' },
+		isActive: ( blockAttributes ) => blockAttributes.term === 'category',
 	},
 ];
 

diff --git a/packages/components/src/slot-fill/context.js b/packages/components/src/slot-fill/context.js
@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { sortBy, forEach, without } from 'lodash';
+import { without } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -95,7 +95,6 @@ class SlotFillProvider extends Component {
 
 	unregisterFill( name, instance ) {
 		this.fills[ name ] = without( this.fills[ name ], instance );
-		this.resetFillOccurrence( name );
 		this.forceUpdateSlot( name );
 	}
 
@@ -109,19 +108,13 @@ class SlotFillProvider extends Component {
 		if ( this.slots[ name ] !== slotInstance ) {
 			return [];
 		}
-		return sortBy( this.fills[ name ], 'occurrence' );
+		return this.fills[ name ];
 	}
 
 	hasFills( name ) {
 		return this.fills[ name ] && !! this.fills[ name ].length;
 	}
 
-	resetFillOccurrence( name ) {
-		forEach( this.fills[ name ], ( instance ) => {
-			instance.occurrence = undefined;
-		} );
-	}
-
 	forceUpdateSlot( name ) {
 		const slot = this.getSlot( name );
 

diff --git a/packages/components/src/slot-fill/fill.js b/packages/components/src/slot-fill/fill.js
@@ -13,8 +13,6 @@ import { createPortal, useLayoutEffect, useRef } from '@wordpress/element';
  */
 import { Consumer, useSlot } from './context';
 
-let occurrences = 0;
-
 function FillComponent( { name, children, registerFill, unregisterFill } ) {
 	const slot = useSlot( name );
 
@@ -23,10 +21,6 @@ function FillComponent( { name, children, registerFill, unregisterFill } ) {
 		children,
 	} );
 
-	if ( ! ref.current.occurrence ) {
-		ref.current.occurrence = ++occurrences;
-	}
-
 	useLayoutEffect( () => {
 		registerFill( name, ref.current );
 		return () => unregisterFill( name, ref.current );

diff --git a/packages/components/src/slot-fill/slot.js b/packages/components/src/slot-fill/slot.js
@@ -62,7 +62,6 @@ class SlotComponent extends Component {
 		const { children, name, fillProps = {}, getFills } = this.props;
 
 		const fills = map( getFills( name, this ), ( fill ) => {
-			const fillKey = fill.occurrence;
 			const fillChildren = isFunction( fill.children )
 				? fill.children( fillProps )
 				: fill.children;
@@ -72,7 +71,7 @@ class SlotComponent extends Component {
 					return child;
 				}
 
-				const childKey = `${ fillKey }---${ child.key || childIndex }`;
+				const childKey = child.key || childIndex;
 				return cloneElement( child, { key: childKey } );
 			} );
 		} ).filter(

diff --git a/packages/components/src/slot-fill/test/__snapshots__/slot.js.snap b/packages/components/src/slot-fill/test/__snapshots__/slot.js.snap
@@ -150,12 +150,31 @@ exports[`Slot should render empty Fills without HTML wrapper when render props u
 </div>
 `;
 
-exports[`Slot should render in expected order 1`] = `
+exports[`Slot should render in expected order when fills always mounted 1`] = `
 <div>
   <div>
-    first
+    first (rerendered)
     second
+    third
+    fourth (new)
   </div>
+</div>
+`;
+
+exports[`Slot should render in expected order when fills unmounted 1`] = `
+<div>
+  <div>
+    second
+    third
+    first (rerendered)
+    fourth (new)
+  </div>
+  <button
+    type="button"
+  />
+  <button
+    type="button"
+  />
   <button
     type="button"
   />

diff --git a/packages/components/src/slot-fill/test/slot.js b/packages/components/src/slot-fill/test/slot.js
@@ -167,7 +167,68 @@ describe( 'Slot', () => {
 		expect( container ).toMatchSnapshot();
 	} );
 
-	it( 'should render in expected order', () => {
+	it( 'should render in expected order when fills always mounted', () => {
+		const { container, rerender } = render(
+			<Provider>
+				<div key="slot">
+					<Slot name="egg" />
+				</div>
+			</Provider>
+		);
+
+		rerender(
+			<Provider>
+				<div key="slot">
+					<Slot name="egg" />
+				</div>
+				<Fill name="egg" key="first">
+					first
+				</Fill>
+				<Fill name="egg" key="second">
+					second
+				</Fill>
+			</Provider>
+		);
+
+		rerender(
+			<Provider>
+				<div key="slot">
+					<Slot name="egg" />
+				</div>
+				<Fill name="egg" key="first" />
+				<Fill name="egg" key="second">
+					second
+				</Fill>
+				<Fill name="egg" key="third">
+					third
+				</Fill>
+			</Provider>
+		);
+
+		rerender(
+			<Provider>
+				<div key="slot">
+					<Slot name="egg" />
+				</div>
+				<Fill name="egg" key="first">
+					first (rerendered)
+				</Fill>
+				<Fill name="egg" key="second">
+					second
+				</Fill>
+				<Fill name="egg" key="third">
+					third
+				</Fill>
+				<Fill name="egg" key="fourth">
+					fourth (new)
+				</Fill>
+			</Provider>
+		);
+
+		expect( container ).toMatchSnapshot();
+	} );
+
+	it( 'should render in expected order when fills unmounted', () => {
 		const { container, rerender } = render(
 			<Provider>
 				<div key="slot">
@@ -192,6 +253,7 @@ describe( 'Slot', () => {
 					<Slot name="egg" />
 				</div>
 				<Filler name="egg" key="second" text="second" />
+				<Filler name="egg" key="third" text="third" />
 			</Provider>
 		);
 
@@ -200,8 +262,10 @@ describe( 'Slot', () => {
 				<div key="slot">
 					<Slot name="egg" />
 				</div>
-				<Filler name="egg" key="first" text="first" />
+				<Filler name="egg" key="first" text="first (rerendered)" />
 				<Filler name="egg" key="second" text="second" />
+				<Filler name="egg" key="third" text="third" />
+				<Filler name="egg" key="fourth" text="fourth (new)" />
 			</Provider>
 		);