Block Registration: add SlotFill to extend a block's description

[jeherve]

• Primary issue: #41236
• Discussion about this: https://github.com/WordPress/gutenberg/pull/44455#issuecomment-1277320695

What problem does this address?

It was previously possible to use React nodes in a block's description, like so:

description: (
        <Fragment>
            <p>
                { __(
                    'This block does something really fancy and complex.',
                    'my-fancy-complex-block'
                ) }
            </p>
            <p>
                { __( 'Here is a detailed description about the things my block does.', 'my-fancy-complex-block' ) }
            </p>
            <ExternalLink href={ supportLink }>{ __( 'Learn more about how to use me', 'my-fancy-complex-block' ) }</ExternalLink>
        </Fragment>
    ),

This allowed adding extra information to a block's description, such as links to support documentation or more.

Unfortunately, this is no longer encouraged since #44455.

What is your proposed solution?

Instead of adding all that information to the block's description itself, and since adding it there can have some unintended side-effects, it would be nice to add a new SlotFill that would be displayed right below the block's description in the editor sidebar, and nowhere else.

[mtias]

@jeherve I'm curious if you'd expect this slot to be rendered wherever a block description is rendered. For example, in block previews in the inserter.

[jeherve]

I would expect it to appear in the primary block sidebar only, not in the previews in the inserter. That's just me though. Maybe this could be a parameter?

[mtias]

So it might be good to contextualize the slot as InspectorBlockInfo or similar instead of something more generic. A parameter would be problematic on its own. it's not easy to anticipate all the contexts in which a description of a block might be rendered where the extender didn't expect.

[fabiankaegy]

Since this ticket hasn't seen any progress since it was originally punted in the 6.3 release cycle, I'm going to talke it out of the release tracking borad. That doesn't mean that it couldn't go into a release if someone works on it. But since it isn't a major priority we don't need to track it in the release board.

[gziolo]

There is a private slot fill that the Query block uses:

• https://github.com/WordPress/gutenberg/pull/49819

We should promote it to the public to resolve this issue.

[jarekmorawski]

We have several use cases for such a feature in the WooCommerce blocks. For instance, we'd like to display a link that opens a feedback modal. I've seen a similar link in WordPress.com that opens each block's documentation page.

There's a risk that placing a slotfill in such a prominent location in the Inspector may lead to abuse and I wonder if we'd put some guardrails in place? For instance, we'd only allow links (with or without icons), but not buttons or notices.

[simison]

Old proposal for API to add links in more declarative way, rather than an all-open slotFill:

• https://github.com/WordPress/gutenberg/pull/11330