Block API: Normalize block type function argument

[gziolo]

Description

Closes #5227.

On the point of name vs. type as an argument; I'd actually be okay with allowing the convenience here of specifying one or the other, as long as it's supported consistently across all functions. Maybe we need an internal function to normalize?

We should address this before 5.0 lands. This won't be a breaking change but it should simplify using the following API methods at least:

• getBlockAttributes
• getSaveContent
• getSaveElement

This PR adds new internal helper method normalizeBlockType which makes use of the following methods more convenient for all plugin developers:

• getBlockAttributes
• getSaveContent
• getSaveElement
• isValidBlockContent

It's going to be possible to pass either block's name as string or block type object as an object as the first param for all of the aforementioned methods. In the majority of cases passing string removes some boilerplate code.

How has this been tested?

All unit and e2e tests still pass.

Types of changes

Refactoring and code enhancement.

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.

[aduth]

Thoughts on?

• getBlockTransforms( direction, blockName ) -> getBlockTransforms( direction, blockTypeOrName ) (Public API)
  • My opinion: I'd honestly like to see this one changed to reverse its argument getBlockTransforms( blockTypeOrName, direction ) to be more cohesive with other APIs
• getBlockDefaultClassName( blockName ) -> getBlockDefaultClassName( blockTypeOrName ) (Public API)
  • My opinion: Should probably be converted.
• getBlockMenuDefaultClassName( blockName ) -> getBlockMenuDefaultClassName( blockTypeOrName ) (Public API)
  • My opinion: Should probably be converted.
• getCommentDelimitedContent( rawBlockName, attributes, content ) -> getCommentDelimitedContent( blockNameOrType, attributes, content )
  • My opinion: Should be left as-is. Internal to serializer, and functions purpose is to compose the raw pieces.

[noisysocks]

A general question (not a blocker!) about our public APIs: Should we be validating their inputs more strictly and e.g. throwing an error if a number or boolean is passed here?

My fear is that we may lose some flexibility to change APIs in the future if there are popular plugins out there that are using our APIs incorrectly.

[gziolo]

Should we be validating their inputs more strictly and e.g. throwing an error if a number or boolean is passed here?

As bad as it sounds, wouldn't it be a breaking change? :)

In overall, this is something we should pay more attention to in the 2nd phase of the project.

[aduth]

My 2¢ : While laudable, as a general pattern it's hard to anticipate all nonsense inputs, and in setting expectations of tolerance while being unable to deliver (or deliver consistently), we're doing more a disservice than we're helping.

[gziolo]

I added change for:

• getBlockTransforms( direction, blockName ) -> getBlockTransforms( direction, blockTypeOrName ) (Public API)

See 896e4b9.

My opinion: I'd honestly like to see this one changed to reverse its argument getBlockTransforms( blockTypeOrName, direction ) to be more cohesive with other APIs

The thing is that blockName is optional in this function. It's often called without blockName which means take all of them.

getBlockDefaultClassName and getBlockMenuDefaultClassName operate only on the name of the block and they use hooks internally which also propagate only class name. I'm not convinced we need to enrich them with block type object. I would skip it.

getCommentDelimitedContent - it's an internal function. We can change it later if we want. However, it feels like it should stay as is because it operates only on a string. We might want to rename it to blockName and update usage of blockName inside the function's body to processedBlockName to make it read better.

[aduth]

This could be partial( getBlockTransforms, direction ). I dunno that I'd care to change it though (given partial's questionable future)