Try: Replace BlockDescription component with block type property

[aduth]

Related: #1555

This pull request explores an alternative to #1555, wherein a block can add its description to the inspector by rendering the <BlockDescription> component in the block inspector slot. The intent here is to treat description as a base property of a block type, rather than one which is specific to the inspector or edit rendering. The purpose being: a description pairs well with other top-level properties (title, icon), may be useful outside the context of edit, is simpler to document for basic block behaviors, and may need explicit arrangement in the block inspector slot (see #1889 caveats).

There is otherwise no functional difference from the behavior implemented in #1555.

Testing instructions:

Verify that the block description is shown in the sidebar "Block" inspector for the selected block.

1. Navigate to Gutenberg > Demo
2. Select a block with a description assigned (e.g. text, image)
3. In the sidebar, switch to Block panel
4. Note that the block description is shown at the top of the block inspector

[westonruter]

One concern with this change is that it wouldn't allow for markup in the description, would it? It also wouldn't allow for multiple paragraphs. I have this in a pending PR: #1625

[aduth]

One concern with this change is that it wouldn't allow for markup in the description, would it?

This is a good point to raise. Technically with this revised implementation, the description could be assigned as a React element and would work just as well.

Related considerations:

• How do we localize strings which need to include markup but mounted in a React component?
  • Related: https://github.com/Automattic/interpolate-components
• Do we want to allow markup (or React elements) in descriptions? Are there other use-cases which would need to access a description but require it to be plain-text?

[swissspidy]

Are there other use-cases which would need to access a description but require it to be plain-text?

As I mentioned a few times, register_post_type() and its description argument come to mind. It's useful for adding short descriptions (1 line, a few words) to post types. That means they can be used more like subtitles.

The <BlockDescription> component is basically a help text component. There can be links in it, formatting, etc. But what if you want to have a short plain-text subtitle/description somewhere? The description would be suitable for that.

tl;dr: Do we need two types of description? A "real" description and something more like a help text? Help text definitely need to allow for markup, while a subtitle might not.

[aduth]

tl;dr: Do we need two types of description?

My hunch is: probably? Thinking for example better explanation of a block's purpose in the inserter (tooltip, subtitle, etc). But these use-cases don't seem very well fleshed out yet.

I'd be fine to punt this for now since there does seem an obvious need for markup in the inspector. Previous consideration still stands so far as needing localization solution for markup-interspersed-React-element-content.

[jasmussen]

In recent developments, the sidebar has become tabbed, with a block option you can choose to have permanently open. As @swissspidy notes, this is a great place to show "help text" for every block.

One of the things I think is important, is to wrap as much block functionality as possible, in as simple a block registration code as possible. And it would be really nice to have help text for every single block that registers itself with a description, using strong visual patterns like this:

We might even want to show a message in the sidebar block tab, that "This block has no description", to encourage block authors to add one.

We definitely do want to allow block authors to add still more stuff to the inspector, down below the help text up top. And we'd want to be sure authors can have links in their help text. But outside of that, I see great value in standardizing some of this stuff.