Block Kit: no way to render help text in a Portable Text block's editing modal

[oliviercp]

What's missing

A plugin that registers a Portable Text block type with admin.portableTextBlocks[].fields gets a Block Kit form in the insert/edit modal. There is currently no way to put a line of guidance in that modal — not once per block, not per field.

Verified against @emdash-cms/admin@0.31.1:

• The modal renders Dialog.Title and then block.fields.map(field => <BlockKitField … />). There is no slot between them.
• BlockKitField's switch handles text_input, number_input, select, toggle, repeater, media_picker. Anything else falls to default: and renders Unknown field type: {type}.
• No element carries a hint / help_text. The text_input branch renders a <label> and the control, nothing else.
• PortableTextBlockConfig.description exists, but it is only read by the slash command menu — the modal never shows it.

So the only ways to get words into that modal today are a real input, a real switch or a real dropdown, each of which looks interactive and stores a value.

Why it matters

Block Kit's form elements are scalar: there is no rich-text element and no way to register an inline mark. A plugin whose block fields need any formatting at all therefore has to define a small plain-text convention (**bold**-style) parsed at render time. Nothing in the editor can hint that such a convention exists.

placeholder is the only surface available, and it has the wrong lifetime: it disappears the moment a field has content, so an author editing an existing block — the common case — sees no hint at all. It also cannot express anything that applies to the block as a whole rather than to one field.

Suggested fix

Option A — a display-only element (preferred). context is already Block Kit's word for muted help text at the block level, so reusing it as an element keeps one word for one idea:

// Element union
| { type: "context"; text: string }

// BlockKitField
case "context":
  return <div className="text-sm text-kumo-subtle whitespace-pre-line">{field.text}</div>;

action_id would need to be optional for this type — it is currently used as the React key and as the form-value key — and the element should be skipped when values are collected on submit.

A legend then becomes the first entry in fields. It works for any plugin and any block, and it composes with the next thing someone wants: a note between two groups of fields, a caution above a destructive toggle.

Option B — cheaper: honour description in the modal.

{block?.description && (
  <p className="text-sm text-kumo-subtle mb-4">{block.description}</p>
)}

One line, no new API surface. The trade-off is that one string then serves both the slash menu (where short is best) and the modal (where a legend may want two or three lines).

The two options are not exclusive — A is the general mechanism, B is a sensible default for blocks that do not need one.

Related, same root

The PT block modal also ignores Block Kit's condition ({ field, eq } / { field, neq }). FormBlockComponent honours it, but the PT block form iterates fields and renders each one with no condition filter — so declared conditions survive serialization through /_emdash/api/manifest exactly as written and are simply never applied. Verified in a running admin: with a select set to one value, every field conditioned on another value still shows.

Mentioning it here only because it is the same gap seen twice: the PT block form is a reduced renderer next to the Block Kit form block. Happy to split it into its own issue if that is more useful.

[MA2153]

Converted this to a discussion as it is a feature request.