Block Deprecations: Provide extra data for isEligible check (#48815)

Co-authored-by: Daniel Richards <[email protected]>

docs/reference-guides/block-api/block-deprecation.md

@@ -37,8 +37,21 @@ Deprecations are defined on a block type as its `deprecated` property, an array
 -   `attributes` (Object): The [attributes definition](/docs/reference-guides/block-api/block-attributes.md) of the deprecated form of the block.
 -   `supports` (Object): The [supports definition](/docs/reference-guides/block-api/block-registration.md) of the deprecated form of the block.
 -   `save` (Function): The [save implementation](/docs/reference-guides/block-api/block-edit-save.md) of the deprecated form of the block.
--   `migrate` (Function, Optional): A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of `[ attributes, innerBlocks ]` compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant.
--   `isEligible` (Function, Optional): A function which, given the attributes and inner blocks of the parsed block, returns true if the deprecation can handle the block migration even if the block is valid. This is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. This function is not called when the results of all previous deprecations' `save` functions were invalid.
+-   `migrate`: (Function, Optional). A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of attributes and inner blocks compatible with the block. As mentioned above, a deprecation's `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant.
+	- _Parameters_
+		- `attributes`: The block's old attributes.
+		- `innerBlocks`: The block's old inner blocks.
+	- _Return_
+		- `Object | Array`: Either the updated block attributes or tuple array `[attributes, innerBlocks]`.
+-   `isEligible`: (Function, Optional). A function which returns `true` if the deprecation can handle the block migration even if the block is valid. It is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. This function is **not** called when the results of all previous deprecations' save functions were invalid.
+	- _Parameters_
+		- `attributes`: The raw block attributes as parsed from the serialized HTML, and before the block type code is applied.
+		- `innerBlocks`: The block's current inner blocks.
+		- `data`: An object containing properties representing the block node and its resulting block object.
+			- `data.blockNode`: The raw form of the block as a result of parsing the serialized HTML.
+			- `data.block`: The block object, which is the result of applying the block type to the `blockNode`.
+	- _Return_
+		- `boolean`: Whether or not this otherwise valid block is eligible to be migrated by this deprecation.
 
 It's important to note that `attributes`, `supports`, and `save` are not automatically inherited from the current version, since they can impact parsing and serialization of a block, so they must be defined on the deprecated object in order to be processed during a migration.
 
@@ -63,7 +76,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', {
 	// ... other block properties go here
 
 	attributes,
-	
+
 	supports,
 
 	save( props ) {
@@ -73,7 +86,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', {
 	deprecated: [
 		{
 			attributes,
-			
+
 			supports,
 
 			save( props ) {

packages/blocks/src/api/parser/apply-block-deprecated-versions.js

@@ -50,7 +50,10 @@ export function applyBlockDeprecatedVersions( block, rawBlock, blockType ) {
 		const { isEligible = stubFalse } = deprecatedDefinitions[ i ];
 		if (
 			block.isValid &&
-			! isEligible( parsedAttributes, block.innerBlocks )
+			! isEligible( parsedAttributes, block.innerBlocks, {
+				blockNode: rawBlock,
+				block,
+			} )
 		) {
 			continue;
 		}