Better organization for block transforms

[mtias]

Block transforms are one of the most important and powerful features of the block editor. They allow switching content types effortlessly and open many paths for users and block developers. They are so useful that it's natural people use them for basic operations (paragraph > heading), layout transforms (paragraph > group, paragraph > row), block replacements (site logo > site title), variations transforms, and everything in between.

Given this reality, the transforms menu has grown a lot, often obscuring basic transforms in favor of niche ones. I think we can improve this situation by making a couple tweaks:

• Define a list of basic transform operations for text: paragraph, heading, list, and quote should always be prioritized and grouped together.
• Define a list of layout related transforms: group, row, columns, stack, cover, etc, and group them together, separated from other content-driven transforms in the list of transforms.

The separation can be just a line separator for content-formatting ones and maybe another flyout menu for layouts. It'd also be fine to do a first pass that just adds a line divider and gathers them together in priority sets.

[jameskoster]

I imagine it would be implemented separately, but it might be good to keep in mind that pattern transforms could be accessible from this menu as well.

[jameskoster]

Here's an example of how the transform menu would look with some grouping:

Obviously it depends on the block, and whether styles are present, but this is already a little unwieldy.

We can simplify things quite a bit by utilising flyouts or similar mechanism:

The 'View patterns' link could open the pattern explorer with the appropriate filter, or engage exploded mode (#39281 (comment)).

[ntsekouras]

We can simplify things quite a bit by utilising flyouts or similar mechanism:

We need to take into account the case of multiple selected blocks. In many of these cases the only available options would be Group and Columns, so it might not make much sense to have a flyout.

This issue also highlights that we need some kind of handling for some block variations(stack, row, etc..).

We also need to find a good way of identifying the group, a block transform should belong to. What is layout transform for example? Could a way to separate them be to check the isMultiBlock: true from a transform? Would we need an explicit new API in transforms? This point is also related to the exposure of block variations in the transforms menu.

[mtias]

I'd like to start with splitting and prioritizing the basic transforms for text blocks. Can we explore some alternates there to see what might work? I can see a minimal implementation that just groups them at the top with a divider, for example.

[jameskoster]

Perhaps mis-interpreting, this list seems very long to me. Unsure of the value vs noise of the sub-divider.

Another option is to use flyouts for methods we don't want to prioritise:

Edit: I suppose this is another option, somewhere between the two above :)

[mtias]

I mean prioritizing paragraph, heading, quote, list, etc for text based blocks. Only the first task, don't do anything to layout transforms.

[jameskoster]

Okay, ignoring styles and layouts for now, here are some options that make use of existing patterns:

[pablohoneyhoney]

Fantastic iterations and variations @jameskoster

Maybe this was done already, but do we need to list out the taxonomies and associations or the more prominent block types to we understand how many max might be listed and it could drive the decision on how best to represent it in the UI? An example, the Inserter style option, are there cases where they are four breaking this solution?

I like the simplicity of the flyout solution, which was considered a while back when we refreshed the toolbar and perhaps the most scalable without getting too long.

As a small note, worth using a separator without gaps, right?

[jameskoster]

To my knowledge no full list has been compiled, although I suppose it must exist somewhere in the code. I think there's a discussion to be had around what determines the number of prioritised transformations – the design, or the code. For example it could be a design decision that only 3 transforms will be prioritised regardless of block type or total number of transforms. This might be preferable because otherwise prioritised transforms would need to be explicitly flagged in the code, which requires additional work and could potentially be abused to the detriment of the UX.

As a small note, worth using a separator without gaps, right?

It's preferable, but the organisation can feel strange when we consider other sections within this menu. Example:

Due to the presence of the Style section it's not clear whether the Pullquote button is part of of the Transform section, or something else entirely.

This is one of the reasons why I prefer the flyout option, it's more holistically scalable:

[mtias]

Let's try the separated list as a first pass.

[pablohoneyhoney]

@jameskoster I guess that's a situation not to worry about yet based on the above conversation and priority, but if needed in the future (with more layout, style transforms), we could add an additional label too: "other transforms" if visible with separator, or "more" in the case of the flyout.

[annezazu]

Noting that this came up as a request, particular for template parts, in the usability testing for the FSE Outreach Program. Rather than selecting "replace", a participant expected to see patterns as options from clicking on the Header icon itself:

[jameskoster]

@annezazu I think @Mamaduka is going to look into this as a part of #42221.

[annezazu]

As part of the sixteenth call for testing for the FSE Outreach Program, the following feedback was shared that seems to capture a shared sentiment of those who participated:

Text transforms in generally worked fine, but feels a bit like a labyrinth. As there are different transforms based on what the current block is. It feels a bit random.

Similar to the efforts to have consistent dimension controls, this feels like another high impact area to make more predictable in time.

[mtias]

@jameskoster can we add a mockup that just does the splitting, please? Without styles or anything extra.

[ntsekouras]

I can work on this one. @jameskoster I'll see to create a simple PR to get things started.

[jameskoster]

Here we go:

[mtias]

Thanks! We can expand from there for layout, media, etc, in the future. One thing to consider, for example, is that layout tools are a lot more useful for multi-block selection, and we already expose them more prominently in the toolbar in those cases. We should probably include Cover in those transforms.

[richtabor]

Organizing further with flyouts is blocked until we have a nested dropdown component, as discussed here. cc. @ciampo

[scruffian]

I think block transforms are pretty tricky to find for such a powerful feature. I'd like to see them exposed elsewhere - maybe in Block Options or Block Settings?

[jarekmorawski]

The new dropdown component with submenus is almost here. Does this mean we can revisit this issue? I'm asking because I ran into a similar use case while working on a new Woo block. It'd benefit from displaying transformation options, patterns, and variations (we call them "types").

I took the liberty of adjusting the block menu to the design of the updated dropdown. Here's how it could look for the Paragraph block:

And how we'd adopt it for the new Woo block. Note the Change type section, which would be owned and managed by WooCommerce blocks. This suggests that the transformation menu should have extensibility points.

I wonder if we can also take this opportunity to rethink the affordances. I assume many new users may not realize that the block icon is interactive and houses settings and features they might've looked for elsewhere. Could making the block icon its own button (and using the separators as button signifiers) or merging the transform menu with the kebab dropdown help make the features inside more discoverable?

I think block transforms are pretty tricky to find for such a powerful feature. I'd like to see them exposed elsewhere - maybe in Block Options or Block Settings?

I think contextual options could work well in conjunction with a dedicated Layout tab in the Inspector. As Matias pointed out, the toolbar is useful for customizing multiple blocks at once, which applies to transformation and layout updates.

[annezazu]

Noting that an effort is underway to audit block transforms: #63635

[mtias]

Do we have a design proposal now the dropdown menu is capable of doing flyouts well? It seems grouping layout tools would be good.

[jameskoster]

Here's the current transform menu for a paragraph block:

That's a lot of options, and aside from the top three they are a bit obscure and add a lot of weight to the menu. Things degrade further when style variations or pattern options are available. Here's an example from Twenty Twenty-Four:

Here's a mockup that attempts to address some of the short-comings:

This could be broken down into the following steps:

• Less common transform options move to a flyout.
• Layout creation options move to a flyout.
• Pattern transforms grouped with layout transforms.
  • This part may need some design attention – the current previews do not map to the DropdownMenu v2 spec.

[ntsekouras]

I experimented on this a bit and I'll share my findings.

Menu (the new one)

In order to have nested menus, we need to use the new component.

1. There are some style differences between the MenuItem component, separators etc that will need to resolved and not hard to do.
2. How do we want to handle the patterns transformations? I think it would be fine to have the new Menu.Item to show the suggestions only on click. This is done for performance reasons if I remember correctly. I'm mentioning this because of the above comment: This part may need some design attention – the current previews do not map to the DropdownMenu v2 spec..
3. The most important aspect though is that every other menu in BlockToolbar is using the old DropdownMenu. What is the suggested path forward with the inconsistency that will be created? Is it acceptable to update this menu and iterate on the others, or it's something that should be done separately for all such menus?

Layout transformations

Noting that I'll expand on some technical details below.

What we want based on this issue is a way to 'mark' some transformations that are layout (Create layout). This is something that will need a new API and there are some nuances.

To provide some context around transforms API a block can have multiple transformations based on the selected blocks. These transforms define the direction of the transformation (from the selected blocks to the result and the other way around), are merged (with some logic) and eventually with props like priority etc.. only one is the 'winner' transform.

An example in core with the above is between core/group and core/media-text blocks. Group block has a 'catch-all' transform that is available for any selected block. MediaText block though has another transform that has bigger priority than the Group's one, and that's the one that will be applied, if we try to transform the MediaText to Group.

The above is important in terms of the API needed. At first it seems that the new API should be part of the transforms API, something like category: 'layout' in the transforms object. The problem with that though is that every transform should have this new category prop and this would be hard, because transforms can be extended by third party blocks and third party blocks have their own transforms too. Without that, we can result in having the Group transform under the Change layout dialog in some cases and under More dialog in others for example.

So, maybe something we could do is define somehow in the block's attributes that a block can be considered a layout block. We can't do this by using the block's category because it already have different usages. With an approach like that we would just check the block's name against that prop that would say it's transforms should be under layout always.

Having said that, this approach doesn't feel right to me (we're mixing Blocks and Transforms APIs).

I'd love some ideas/feedback about a possible solution. --cc @WordPress/gutenberg-core @gziolo

[jameskoster]

How do we want to handle the patterns transformations?

Is it actually feasible for the pattern transforms to live in a flyout menu; can Menu.Item support a satisfactory design (list of pattern previews with visible text label)? I might be wrong but I don't think it's set up that way.

If we're going to load the previews on click, then we might consider displaying the options in a modal. That might work better when there are many patterns too.

Is it acceptable to update this menu and iterate on the others

In an ideal world we migrate all menus as soon as possible. But I don't think it's the end of the world if there's a temporary mismatch.