Replace BTooltip with a Popover API based tooltip

What

Replaces the bootstrap-vue tooltip (GlTooltip / v-gl-tooltip) with an engine built on the native Popover API and @floating-ui/dom.

👉 Integration MR here: gitlab-org/gitlab!255018

Why

  • bootstrap-vue is Vue 2-only and blocks the Vue 3 migration.
  • The Popover API renders the tooltip in the browser's top layer, so it is never clipped by overflow or covered by other content. This removes the container machinery (container prop, directive arg, setGlTooltipDefaultContainer) that existed only to escape clipping.
  • Positioning still needs @floating-ui/dom (already a dependency): the Popover API does not anchor elements, and CSS Anchor Positioning is not Baseline yet (no Firefox).

Supersedes !5646 (closed), which built the same architecture on @floating-ui/dom alone, without the Popover API.

Notable changes

  • Browserslist bumped to baseline widely available (mirrors gitlab-org/gitlab).
  • Both the directive and GlTooltip append the tooltip element to body. The component renders its slot there with the BVTransporter that GlModal also uses (<Teleport> in Vue 3), so a tooltip never sits inside its target or the elements around it.
  • New showGlTooltip(id?) / hideGlTooltip(id?) exports replace the bootstrap-vue bv::show::tooltip / bv::hide::tooltip root-bus pattern. They match the same way bootstrap-vue did: by the target element's id or the tooltip's own id (the directive's id option or GlTooltip's id prop), for both the directive and the component. Without an id they act on every tooltip on the page.
  • Behavior kept from bootstrap-vue: the target's title is moved aside as soon as hover or focus starts (no native tooltip during the show delay), only :focus-visible focus opens a tooltip, triggers on natively disabled targets are ignored, a focusout doesn't close a tooltip while the pointer is still on its target (as with clipboard.js copy buttons), a tooltip doesn't show for, or hides when, its target is removed or hidden with display: none, and an invalid delay, like null, means no delay. Binding the directive again updates its tooltip in place, and a tooltip with empty content doesn't show, or hides when its content is cleared, for <gl-tooltip> too.
  • A tooltip stays attached to its target: an offset or the viewport edge can shift it only as far as it still overlaps the target, and its arrow stays off the rounded corners.
  • New: Escape closes an open tooltip. This meets the "dismissible" requirement of WCAG 2.1 SC 1.4.13 Content on Hover or Focus (Level AA): content shown on hover or focus can be closed without moving the pointer or the focus. bootstrap-vue tooltips had no way to do that.
  • HTML titles (.html / html) are sanitized with DOMPurify, with the SafeHtml directive's config, and inserted as a DOM fragment.
  • .tooltip-inner is kept and, as in Bootstrap, is the only element with the 200px max width, so consumers can still widen tooltips through it.
  • The popover reset and fade styles only apply to .gl-tooltip elements with a popover attribute, so hand-built .gl-tooltip elements (e.g. the code block actions in gitlab-org/duo-ui) keep working.
  • Breaking change (major): see the changeset for the full list.

How to review

The branch has thirteen commits, best reviewed one by one:

  1. Target Baseline widely available browsers: the browserslist change the Popover API needs.
  2. Replace BTooltip with a Popover API based engine: the engine, the component, the directive, their styles and specs, the changeset, and the BSV migration inventory. Its commit message explains the design and lists what stays the same as bootstrap-vue.
  3. Remove tooltip options the new tooltip no longer supports: two small consumer changes in GitLab UI (GlLabel, GlSingleStat).
  4. Add tooltip stories and update their visual snapshots.
  5. Update the tooltip docs for the new tooltip.
  6. Keep tooltips attached to their target and the arrow off the corners: found in manual testing. A large offset, like .o5000, or the viewport edge moved a tooltip away from its target and its arrow onto a rounded corner.
  7. Sanitize HTML tooltips with the SafeHtml directive's config: one shared DOMPurify config instead of a copy that could drift apart.
  8. Treat a null tooltip delay as no delay: from Duo's review, a null delay threw on the first hover.
  9. Keep GlTooltip's engine instance out of Vue's reactivity: from Duo's review. Vue 3's reactive proxy kept every destroyed GlTooltip in the engine's registry.
  10. Mark the tooltip breaking changes as BREAKING CHANGE: the changelog convention for BootstrapVue removals, plus a note on the untranspiled dist syntax.
  11. Remove the vendored bootstrap-vue tooltip styles: dead since the new tooltip; the built CSS is unchanged.
  12. Update an existing tooltip when the directive is bound again: so gitlab-org/gitlab's v-tooltip-on-truncate no longer closes an open tooltip on every update.
  13. Do not show GlTooltip with empty content: as BTooltip did, for the component path too.

Required next steps (integration MR in gitlab-org/gitlab)

  • Add a jsdom Popover API shim (!262883, in spec/frontend/__helpers__/dom_shims/popover.js).
  • Move the ~20 bv::show::tooltip / bv::hide::tooltip call sites behind showGlTooltip / hideGlTooltip helpers (!264610). The integration MR points those helpers at the new exports and deletes the two constants.
  • Update feature specs to the new .gl-tooltip markup (!262798).
  • Hide tooltips on mouseleave rather than mouseout (!267548).
  • Validate tooltip behaviors in Storybook and the integration branch.
  • Point the integration branch at the latest package.
  • Release the Duo UI fix for the removed bv::hide::tooltip root event (gitlab-org/duo-ui!865 (merged)), and pick it up in gitlab-org/gitlab, before this major: gitlab-org/gitlab!270724 (merged)

Follow-ups after the release

  • In gitlab-org/gitlab: import showGlTooltip / hideGlTooltip from @gitlab/ui directly, drop the helpers module, and remove the now-dead container / boundary plumbing in tooltips.vue.
  • In gitlab-org/gitlab: remove the .viewport / .window modifiers (about 70 files) and the boundary / container keys of v-gl-tooltip values, which the new directive ignores.
  • With the GlPopover migration: hide open tooltips and popovers when the page goes into the back/forward cache, in one place (gitlab#604140). Today only popovers get that, through tooltip_mixin.js.
  • The open "potential follow-up" threads below (the $on usage in tooltip.vue, the PLACEMENTS in tooltip_engine.js), as follow-up issues.
Edited by Vanessa Otto

Merge request reports

Loading
Loading