Update Tooltip + Popover design guidelines and examples

[mceledonia]

Re: #1081 CC @mcarrano @mmenestr

Tooltip + popover use case clarification

I don't think we ever got around to updating the design guidelines or .org examples of these as they relate to the above issue. I remembered this issue and shared on a product meeting after some inconsistencies were pointed out between the usage of tooltips vs. popovers, and got some good feedback/thoughts from @jgiardino which made me think this could use some more discussion to ensure we're getting to the best solution.

The overall goal of the above is to clarify and differentiate between tooltip and popover use cases to reduce overlap and confusion. There are some interaction details which should be clearly mapped out with the new tooltip direction.

---

Notes from the earlier discussion -

In general, tooltips are being scoped down (labels for icon buttons) and popovers are being scoped up (in-context help) in terms of use cases.

Tooltips are proposed above to now be triggered on hover or click, with each one entailing their own interaction details. Typically hover is not persistent and goes away as focus moves away, click is persistent with a close/x action. This leaves the question of when to use hover vs. click.

---

A possible solution from carbon (see documentation here)

I like how carbon solves this (they just have one component, tooltip) by splitting out their variants into 3 interactions: Tooltip, Icon Tooltip, and Definition Tooltip. We already use all of these, but with less clarity and more overlap between all of their interactions.

• Their Tooltip is essentially our popover, but always triggered with a click and persistent. It can contain actionable elements but regardless is a click-triggered, persistent element. I think this would work well as our new popover component pattern.
  Product change: Some products are using tooltips for in-context help which trigger on hover. This would change those to popovers, and trigger on click.

• Their Icon tooltip is what I've proposed our current tooltip to be scoped down to. Hover-triggered label of an icon action, which would be our new tooltip pattern.
  Product change: None

• Their Definition tooltip is our term definition on description list, triggered by hover. This would be an exception to the above rules, providing a term definition in a hover-triggered interaction using its own styling.
  Product change: Likely none, but the examples on pf.org are showing a click interaction to trigger these, when they could be hover.

---

Conclusion

I think adopting these 3 main interactions (which we already have+utilize, just more spread out), should solve the above goal and questions resulting from it.

Tooltip - Always hover - Label for icon actions
Popover - Always click + persistent - In-context help or addl. info, can contain actionable elements like links or buttons
Definition tooltip - Always hover - In-context definition for terms, uses dotted underline on said terms

[jgiardino]

Thanks for outlining these different types, @mceledonia! What you describe here makes sense.

Another use case where we currently use tooltips is to explain why an action is disabled. It would be nice to add this for consideration in any updates to design guidelines.

Aside from that use case, I could see potential confusion regarding whether the definition tooltip should be used for a form element. I think your proposal is that we'd still use a popover for any information we need to provide for a form, but it might be good to call this specific use case out.

[mcarrano]

@mceledonia I think your analysis makes sense, also. However, we already have an implementation for what you are calling a "definition tooltip" (we call it a description list) that is different from that. We are using a popover that is triggered on_click like field help on a form. See https://www.patternfly.org/v4/components/description-list#term-help-text I'd worry that it would be breaking to change that. For the other use cases, I agree that we should make sure our documentation reflects this consistently.

[mmenestr]

I feel like this can be boiled down to 3 different tooltip/popover types:

1. Icon tooltip: limited to "Hover-triggered label of an icon action" like you said
   

2. Click popover: A popover activated on click, which is what we have today to for bigger descriptions, with ability to add actions
   

3. [new] Hover popover: A popover activate on hover that is non-dismissable. We would introduce this variation for the edge cases, like when we want a tooltip/popover to explain why something is disabled, or other use cases that happen on hover, outside of situations where you're describing an icon. This could require a new variation of popovers to be made which could be disruptive, but in theory, we'd keep everything the same, it would just be up to products to slowly start adopting this new variation in the right places

I think this would cover every use case, and scope down the tooltip like we want. And it would stay separate from what we do for description lists.

[mcarrano]

Opened patternfly/patternfly-react#7072 to add this option to the React component. @mmenestr can you open whatever doc issue we need to update design docs? Thanks.

[mmenestr]

Already created here patternfly/patternfly-org#2871
@mcarrano

[mcarrano]

Thanks @mmenestr Going to close this then.