Block Tips API

[youknowriad]

With the introduction of the inserter help panel in #16813, we have room to explore showing previews of blocks before inserting them into the content.

In order to achieve that in a clean way, each block needs to define an example set of attributes to "fill" its preview content.

This could look something like:

const blockSettings = {
  // ... other settings

  example: {
      attributes: {
          content: __( 'Content of the block' )
      },
      innerBlocks: []
  }

}

This data need to be internationalized properly and can contain both attributes and innerBlocks.

Style Variations

In the style variations picker, we're relying on the current data of the block to preview the changes, this also often results in a less than ideal experience since, depending on the current data of the block, the preview might be "pretty" or not. Designing the example data to fit that use-case will also improve the experience there.

---

Edit: Example API is merged, this is left open to track the tips API proposed in #16979 (comment)

[mtias]

I think this is a good evolution and would simplify some interactions for people that are creating selectable templates (the example content is already defined there, in a way, this would consolidate it).

A few things to consider:

• Is there any overlap with "Patterns"? The definition is going to be pretty much the same. Is there a world where we absorb this in "patterns" and show the first one as an example in the preview?
• I'd like to also consider "tips" a bit here (Compile a list of possible block-specific tips #16595), since my expectation is they'd be defined when registering a block as tips: [ ] and both of these would increase the API surface area.

[youknowriad]

Is there any overlap with "Patterns"? The definition is going to be pretty much the same. Is there a world where we absorb this in "patterns" and show the first one as an example in the preview?

Good question, They do seem to have the same shape. So an option could be. If a block has only one pattern, use it as an example. But if a block has multiple patterns, there's a question to be asked, whether the first pattern is the one that fits the "preview" the best. It might not always be the case.

I'd like to also consider "tips" a bit here (#16595), since my expectation is they'd be defined when registering a block as tips: [ ] and both of these would increase the API surface area.

👍

[mtias]

But if a block has multiple patterns, there's a question to be asked, whether the first pattern is the one that fits the "preview" the best. It might not always be the case.

In one of the original mockups there was a "skip" button for patterns, which would default to initial state.

Where it gets a bit tricky is that patterns don't necessarily come with content defined, it can be only configuration attributes (number of columns, widths, etc) and we still need content for example preview.

[youknowriad]

Also, lately I've been wondering if Patterns are static data like the example here where we just replace the entire block with it, or are more like "functions" where they take the current state of the block and alter it. For example, can decide to keep some attributes, change inner blocks... but not necessarily "reset" everything.

[retrofox]

I'm not completely aware of how complex a block could get, but make sense adding a reference (or something) to those parts/elements of the blocks which really want to preview?
I think on those elements that need to be hidden in the preview such as the inserter element, drop zone, etc. No make sense show them.
Right now we are using a kind of elements blacklist and applying display none.

But thinking well and going forward, we could filter those blocks/elements used to the preview, and getting rid of the rest. It will improve performance considerably.

[retrofox]

Another concern which comes to my mind is the preview and its integration with themes. AFAIK, themes have the capability to tweak the styles of the editor.

For instance, the preview for a dark theme looks like the following:

I wonder if make sense dive on this in order to create a better preview consistent with the theme. For instance, in the screenshot above, the preview should show the background color black in the whole thumbnail.

[talldan]

This seems to also be tracked in #17091. I'll close this as I feel the other issue has a clearer description.