[Lens] Move function help popover triggers to extraAction in related EuiListGroupItem

[MichaelMarcialis]

Per the original design direction for the Lens help popovers, we should plan to move the current Date histogram and Moving average popover trigger buttons from their current locations (in the field selector form area) to instead appear as an extraAction in that function's EuiListGroupItem. Doing so will:

• Allow users to access the help popover for a given function without requiring them to actually change to that function.
• Place the tiggers in closer proximity to their related function, rather than being in closer proximity to the field selector.

Originating issue: #81780
Enhancement to previous PR: #86821

[elasticmachine]

Pinging @elastic/kibana-app (Team:KibanaApp)

[flash1293]

@MichaelMarcialis I started to work on this but it seems like there is not enough space to render help icon next to the longer labels (it's though luck the longest names Date histogram and Moving average are the ones with help popovers):

I already reduced the gap between the columns but it's still too tight in a lot of resolutions:

Do you still think it's worth doing this?

[MichaelMarcialis]

Thanks for investigating this, @flash1293! Yes, I do think this is still worth exploring. The current experience of asking users to first select a function and then view documentation explaining that function being tied to the field selector is confusing and and could benefit from this enhancement. I think it's far more desirable for users to be able to learn about the functions before being forced to make a selection.

The original intent was that the inline documentation icon buttons would only show when hovering a EuiListGroupItem, rather than always showing them. I was hoping that in doing so, we would regain that horizontal real-estate the icon button took up when not showing, preventing truncation when possible. However upon reviewing the EUI docs, it looks like that is not how this component functions. Instead the icon button is just given a zero opacity but still takes up the same horizontal real-estate. Given that fact, there are three possibilities that come to mind for possible exploration:

• We can try using the wrapText prop on the parent EuiListGroup to allow text to wrap (rather than truncate). This will prevent the truncation from occurring, but will cause those offending list items to break a line (which has the potential to look odd; will need to see to be sure).
• Explore responsive styles that will turn the two columns of functions into a single column at a certain breakpoint.
• Attempt to shorten the offending function names. This is probably the least desirable/possible of the options, as "Date histogram" and "Moving average" don't sound like they can be easily shortened, but throwing the notion out there in case I'm wrong.

Any thoughts on trying one of those solutions?

Side note: can we also change the use of the help icon to documentation? I should have mentioned this earlier, but the designs for this predated the creation of our new inline documentation icon.

[flash1293]

The current experience of asking users to first select a function and then view documentation explaining that function being tied to the field selector is confusing and and could benefit from this enhancement

I can see the point, I actually don't know how important it is in practice, for a bunch of reasons:

• The date histogram help popover is not really describing date histogram in general, it's mostly describing the details of how the "auto interval" gets picked. I would argue it's not very relevant before picking the function
• Switching between functions is not a destructive operation, it's possible to switch back without losing anything
• Just in general, I think these help popovers were more meant for describing the tiny little details in how these functions behave to allow the user to learn what exactly is going on if they can't fully understand what's rendered; less about a help to figure out which function to choose in the first place

We can try using the wrapText prop on the parent EuiListGroup to allow text to wrap (rather than truncate)

This is how it would look like, not the biggest fan TBH but it's also not terrible:

Explore responsive styles that will turn the two columns of functions into a single column at a certain breakpoint.

That's an option, but to keep the rest of the form elements above the fold (which is especially important IMHO for the field select), we would need to give the function list a max height and make is scrollable afterwards which will make it much harder to pick a function - IMHO that would be worse than not having the help text available before picking the function.

Attempt to shorten the offending function names. This is probably the least desirable/possible of the options, as "Date histogram" and "Moving average" don't sound like they can be easily shortened, but throwing the notion out there in case I'm wrong.

For Date histogram I like Over time - "histogram" is very technical anyway. I have no good idea for moving average

[MichaelMarcialis]

• The date histogram help popover is not really describing date histogram in general, it's mostly describing the details of how the "auto interval" gets picked. I would argue it's not very relevant before picking the function

Can the same be said for all the other functions' inline documentation (i.e. not describing the function)? Or is this an issue specific to the date histogram function?

This is how it would look like, not the biggest fan TBH but it's also not terrible:

Yeah, I agree. This isn't very pretty at all. I retract that suggestion 😅

One additional thought that came to mind is having a single inline documentation popover for all available functions with a table of contents listing each function (similar to how we approach documentation in formula). This popover could be triggered via a single icon button adjacent to the "Functions" heading. That would prevent encroaching on the EuiListGroupItem text, while still allowing users to access information about the functions before being forced to select one. If such a direction is of interest and requires a design to be made, let me know and I'll add it to my to-do list.

[flash1293]

Besides moving average (which is describing what the function is doing, not some special part of it, but with a lot of detail so I still think it's overwhelming for choosing a function), I think we only have it for the granularity option of intervals:

This is pretty specifically about a special setting within the function, not about the function itself.

[flash1293]

I just realized my comment above was probably a bit off-topic

Can the same be said for all the other functions' inline documentation (i.e. not describing the function)? Or is this an issue specific to the date histogram function?

I think that was the main intention of these documentation popovers - explaining the small things that are not obvious / more complex under the hood than they seem.

One additional thought that came to mind is having a single inline documentation popover for all available functions with a table of contents listing each function (similar to how we approach documentation in formula). This popover could be triggered via a single icon button adjacent to the "Functions" heading. That would prevent encroaching on the EuiListGroupItem text, while still allowing users to access information about the functions before being forced to select one. If such a direction is of interest and requires a design to be made, let me know and I'll add it to my to-do list.

Based on the thing right above - I'm not sure whether it would help in this specific case (but it's a weakly held opinion). As the help descriptions are pretty specific about the "hard to understand/infer" parts of the functions (not general descriptions of the functions), it seems unlikely to me a user would want to read into them without having them selected already (and maybe wondering why the behavior in one specific place is different than they expected). The formula help to me is more of a reference of what exists in terms of functions and which parameters they have (which is handled by the list group component itself for quick functions). For quick functions, I can see this kind of overview becoming useful if we would have at least some documentation for each of the functions, like when to use it (and maybe also more general information like what Elasticsearch agg is used under the hood, what are possible advanced options, why are certain things allowed / not allowed, ...) - but that's a larger project in itself - there's definitely things to be said about each of them, but I don't know whether this is a pain point of the current UI or not (@ghudgins what do you think? Is it worth digging deeper into this at the moment?)

Happy to be convinced otherwise here.

[MichaelMarcialis]

@flash1293: I agree with you that my aforementioned additional thought of having a single inline documentation popover would only work and have value if it housed descriptions for all available functions (rather than only a select few functions as we currently do). Since that would be a larger effort/issue, let's put that idea aside.

Let's instead discuss your doubts on this being a pain point. Even assuming your instinct is correct and that users would be more interested in learning more about a function after it has been selected, are we confident that placing the action to trigger such function-centric documentation on the field selector makes sense from an information architecture perspective? Would a user interacting with the documentation icon button on the field selector think it to be a description of the function they chose in the previous section? Or is it more likely that the user would think it would be documentation pertaining more to field selection? My instinct tells me the latter would be more likely, and another reason why I feel more comfortable with the documentation trigger being in closer proximity to the function selection area instead.

One final thought: what if we proceeded with using the documentation icon button that appears on hover via the extraAction prop (as described originally), but slightly increased the min-width of the flyout and sidebar (currently at 320px) at appropriate breakpoints to prevent the truncation or line breaking of function text in the majority of cases?

CCing @ghudgins in case he has input as well.

[flash1293]

are we confident that placing the action to trigger such function-centric documentation on the field selector makes sense from an information architecture perspective

No, I agree, the function selector is a more natural place for this.

One final thought: what if we proceeded with using the documentation icon button that appears on hover via the extraAction prop (as described originally), but slightly increased the min-width of the flyout and sidebar (currently at 320px) at appropriate breakpoints to prevent the truncation or line breaking of function text in the majority of cases?

I like that approach - it would take a bit of screenspace away from the chart but I guess it wouldn't be too bad. I can build a version of this.