[dashboard][embeddable] document interfaces embeddables can/should implement and how that impacts dashboard features

[nreese]

Dashboard uses actions to allow plugins to extend panel functionality. Below are some common triggers

1. CONTEXT_MENU_TRIGGER trigger adds an action to a panel's context menu.
2. PANEL_BADGE_TRIGGER trigger adds a badge to a panel's title bar.
3. PANEL_NOTIFICATION_TRIGGER trigger adds a notification to the top-right corner of a panel.

Actions use compatibility checks to verify a panel supports the action. Actions are not displayed when a panel fails a compatibility check. Compatibility checks verify the panel supports the required interfaces needed by the action. For example, the filters notification badge action compatibility check ensures that a panel implements the unified search interface and provides filters$ or query$.

The problem is that there is no comprehensive list interfaces that panels should expose. This can lead to issues such as #193598.

There should be a table that details all actions shipped with Kibana. Each action should describe the interfaces needed for compatibility so that embeddable authors can use this reference to know which interfaces and how interfaces are used to support dashboard features.

[elasticmachine]

Pinging @elastic/kibana-presentation (Team:Presentation)

[Heenawter]

Summarizing my thoughts from our team meeting:

Since documenting every action and its interfaces would be a large effort, I wonder if a "good enough" solution would be to create a list of "common bugs" and document it there? So in a case like this, we could list "Actions not showing up" and document how you should resolve this. And before an embeddable is ready to be merged, we could point people towards the common bugs section to verify that their embeddable doesn't suffer from any of them.

Not ideal, but possibly a decent mid-term effort 🤷

[nreese]

Discussed steps for this effert at todays embeddable sync

1. add JS docs to all interfaces in packages/presentation that explains what they control
2. add example plugin that provides a matrix of all runtime actions per trigger. Matrix should define what action does and show type of embeddable that supports actions.