[Global header] Create API to register application menu links

[ryankeairns]

Describe the feature:
As part of the new global header, application menus will be relocated from within the page to the right end of the lower header bar as seen below:

Describe a specific use case for the feature:
As a plugin author/product team, I should be able to add my application menu to the header from my plugin using a framework-independent API.

This new header API should support existing menu designs by accommodating the following content:

• Dynamic menus that change based upon state (e.g. read vs edit modes)
• Mixed menus that display both links and buttons
• Links and buttons that display popover menus (e.g. a Share menu)

cc:/ @joshdover @myasonik @alexfrancoeur

[joshdover]

From a plugin perspective, I think we should provide this API via a new HTMLElement parameter exposed to the mount function that is called when an application is mounted. This allows for a consistent API and enables plugins to use React portals for mounting part of their app tree within this element.

Specifically, I think a headerActionsElement or something similar should be added to the AppMountParameters type, providing an API like:

core.application.register({
  id: 'myApp',
  mount({ element, headerActionsElement }) {
    ReactDOM.render(
      <MyApp headerActionsElement={headerActionsElement} />,
      element
    );

    return () => { ReactDOM.unmountComponentAtNode(element) };
  }
);

const MyApp = ({ headerActionsElement }) => {
  // Simple example, probably your whole app would not be these buttons :)
  return ReactDOM.createPortal(
    <HeaderActions />,
    headerActionsElement
  );
};

I think the tricky part will be actually implementing this API. As it is right now, the Chrome UI is separate from the Application UI code, though they are mounted within the same React tree. Most likely we will need to pass a React ref to both the Chrome component and the app router component so that the HTMLElement can be accessed by the app's mount function.

There could be some timing issues here as well that we may need to workaround to ensure that the headerActionsElement and main app element are both "fresh" before we render the next application. By "fresh" I mean they are new div elements that are not shared with the previous app to minimize any issues from apps not cleaning up properly.

[elasticmachine]

Pinging @elastic/kibana-core-ui (Team:Core UI)

[joshdover]

This new header API should support existing menu designs by accommodating the following content:

* Dynamic menus that change based upon state (e.g. read vs edit modes)

* Mixed menus that display both links and buttons

* Links and buttons that display popover menus (e.g. a Share menu)

How many of these features do we want to implement in the Core API vs. allowing applications to do this themselves (optionally, with some helper components)?

My previous comment was made with the assumption that we would allow applications to render anything they want in that space, but if we want to enforce consistency in how that UI looks then we may want to use a different approach. If we do want to enforce/encourage consistency we can either have a more constrained API that provides these features, or we could provide helper React components that provide these features.

More constrained API

• Pros:
  • Ensures that all UI implementations have consistent styling, layout, and content
• Cons:
  • Makes implementing an MVP more work
  • Makes the Core API more complex
  • Makes this space less flexible
  • May be an awkward API if it's not React-based (which no Core APIs are)

Helper React components

• Pros:
  • More natural for applications to integrate with
  • Can provide the same consistency
  • Allows plugins to use this space for something that does not follow the out-of-the-box UI pattern
• Cons:
  • Less obvious / discoverable
  • May lead to inconsistency if applications don't use the helpers

I lean heavily towards "helper react components" option, but wanted to gut check this with the UI developers. Additionally, should we consider these helper components as in-scope for this issue (and worked on by the Platform team) or would the Core UI team prefer to implement these components?

[ryankeairns]

@joshdover I completely agree with option 2 and these can be considered out of scope for the initial version. My main objective in pointing out those use cases was simply that we keep this open-ended enough that we don't preclude teams from essentially keeping the menu they currently have.

As for the helpers, I think we're safe to punt on that for now since a) it's no different than what we allow today b) this entire effort seems to only impact apps under the Kibana grouping (as of now; 3rd party plugins aside) and c) our biggest blocker to this effort is simply having an API for this new header to land... so keeping it simple is in our best interest :)

Thanks for catching that point and providing options.

[myasonik]

What sort of helper components do you think we'd need? All the stuff that goes into there right now is basically EUI buttons, popovers, and context menus. What else do we need?

[joshdover]

Great, we'll keep the scope for this issue to just implementing the basic API I outlined above (or similar).

What sort of helper components do you think we'd need? All the stuff that goes into there right now is basically EUI buttons, popovers, and context menus. What else do we need?

Depends on how far we want to go. In the last meeting we discussed wanting to support collapsing this area and having different display modes for different screen sizes. I could imagine a component like this that handles this for you:

<HeaderAppControls
  primaryAction={{ title: "Save", onClick: save }}
  actions={[
    { title: "Fullscreen", onClick: toggleFullcreen, fallbackIcon: "" },
    { title: "Cancel", onClick: cancel, fallbackIcon: "" },
  ]}
/>

[elasticmachine]

Pinging @elastic/kibana-platform (Team:Platform)

[ryankeairns]

For version 1 then, the header would presumably have some sort of wrapper (e.g. EuiFlexGroup) for the menu area within which I can pass a set of EUI components, right?

If so, then we'll likely need to document the structure of that, at a minimum. Something like "Wrap each EuiButton / EuiButtonEmpty in an EuiFlexItem"... or do we say 'Pass an array of links (EuiButtons)' and the header wraps each in an EuiFlexItem?

I don't mean to dictate the actual solution, but this has me wondering how we could automatically convert to an overflow menu for smaller screens. Which, in turn, seems to have an impact on the shape of the API perhaps.

cc:/ @cchaos

[myasonik]

I don't think the API is going to know anything about EUI... It's just exposing a div or something to slot content into.

For now, I think teams can just put in whatever they want into that slot. And we can rollout a helper component per Josh's example if we want to standardize but that can come down the line.

Until then, teams can be/are responsible for handling their own narrow viewports and such.