Popover and tooltip API improvements

[gfellerph]

Tooltips and popovers are a much discussed topic.

• [components]: Tooltip refactoring #4170
• Tooltip & popover visibility #4455
• Z-index guidelines #4407
• [bug]: post-popovercontainer promotes to Top Layer, causing UI overlap issues #4398
• Add optional safe triangle to <post-popovercontainer> #4169
• post-tooltip improvements #3823
• Popovercontainer: emit close event after animation #3204

This is a proposal to define a more flexible API and clean up some issues that have arisen after the first implementations have been used in the real world.

Distinction

Tooltip

A means of displaying a description or extra information about an element, usually on hover, but can also be on click or tap.¹

Semantically, tooltips are linked to the trigger element through aria-describedby so the tooltip text is automatically being read by screenreaders when focus is on the trigger.

Popover

An element that pops up from another element over other content; it differs from a tooltip in that it is usually triggered via click instead of hover and can contain interactive elements.²

Semantically, popovers act as disclosure content which is not linked to the trigger. The trigger has an aria-expanded attribute to communicate the current state of the popover.

Issues with the current implementations

• Hoverable tooltips get in the way of the cursor when there are a lot of buttons in a table. To resolve this issue, a delay option was added with Tooltip: add delay option #3213. The delay resolves the issue in most cases and is compatible with recommendations from Accessibility experts like Sarah Higley (https://sarahmhigley.com/writing/tooltips-in-wcag-21/#best-practices-summary). Still, it feels like a workaround and not a real solution to the issue at hand
• Customers request large content to be shown on hover ([bug]: Tooltips add shadow on optional arrow #4290). A tooltip is semantically incorrect in this case but the popover does not show up on hover
• Devs reported difficulties with setting id attributes for all the things. An alternative attribute has been proposed to get around the side effects of id, but was dismissed as the uniqueness is wanted here ([components]: Tooltip refactoring #4170)
• ng-bootstrap popovers provide a way to be opened on hover which is missing from our implementation (https://ng-bootstrap.github.io/#/components/popover/examples#autoclose

Tooltip proposal

Tooltip props

• arrow, boolean prop that will display an arrow, false by default (because that's what boolean props should be)
• delay, [open-delay]|[open-delay close-delay] if it's a number, open delay in milliseconds, if it's a string of two numbers, e.g. delay="200 400", the first number is the open delay and the second the close delay, defaults to undefined
• placement, string, one of the floating ui placement possibilities, defaults to 'top'
• no-hover, boolean that defaults to false. Can be used to hide the tooltip when the cursor leaves the trigger, making the tooltip not hoverable. This is not accessible, but a requested feature that would be worked around if not there
• id, string used to connect <post-tooltip-trigger> with the target <post-tooltip>, optional if the tooltip is nested inside the trigger

Background colour can be set by palette utilities.

Tooltip trigger props

• for, string connects the trigger to it's tooltip, optional if the tooltip is nested inside the trigger

Setup

<!-- Tooltip is connected via for/id attributes -->
<post-tooltip-trigger for="bold-description">
  <button>B</button>
</post-tooltip-trigger>
<post-tooltip id="bold-description">Bold</post-tooltip>

<!-- Tooltip is nested inside the trigger, no for/id attributes necessary -->
<post-tooltip-trigger>
  <button>B</button>
  <post-tooltip>Bold</post-tooltip>
</post-tooltip-trigger>

Popover proposal

Popover props

Popover trigger props

• for, string connects the trigger to it's popover, optional if the tooltip is nested inside the trigger
• `

Setup

<!-- Popover is connected via for/id attributes -->
<post-popover-trigger for="more-info">
  <button>show info</button>
</post-popover-trigger>
<post-popover id="more-info">
  <h3>Additional info</h3>
  <p>Lorem...</p>
  <a href="/goto">Read more about it</a>
</post-popover>

<!-- Popover is nested inside the trigger, no for/id attributes necessary -->
<post-popover-trigger>
  <button>show info</button>
  <post-popover>
    <h3>Additional info</h3>
    <p>Lorem...</p>
    <a href="/goto">Read more about it</a>
  </post-popover>
</post-tooltip-trigger>

Footnotes

1. https://component.gallery/components/tooltip/ ↩

2. https://component.gallery/components/popover/ ↩