Loading
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.
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
overflowor covered by other content. This removes the container machinery (containerprop, 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
GlTooltipappend the tooltip element tobody. The component renders its slot there with theBVTransporterthatGlModalalso 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-vuebv::show::tooltip/bv::hide::tooltiproot-bus pattern. They match the same way bootstrap-vue did: by the target element'sidor the tooltip's ownid(the directive'sidoption or GlTooltip'sidprop), 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
titleis moved aside as soon as hover or focus starts (no native tooltip during the show delay), only:focus-visiblefocus opens a tooltip, triggers on natively disabled targets are ignored, afocusoutdoesn'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 withdisplay: none, and an invalid delay, likenull, 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
offsetor 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 theSafeHtmldirective's config, and inserted as a DOM fragment. .tooltip-inneris 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-tooltipelements with apopoverattribute, so hand-built.gl-tooltipelements (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:
- Target Baseline widely available browsers: the browserslist change the Popover API needs.
- 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.
- Remove tooltip options the new tooltip no longer supports: two small
consumer changes in GitLab UI (
GlLabel,GlSingleStat). - Add tooltip stories and update their visual snapshots.
- Update the tooltip docs for the new tooltip.
- 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. - Sanitize HTML tooltips with the SafeHtml directive's config: one shared DOMPurify config instead of a copy that could drift apart.
- Treat a null tooltip delay as no delay: from Duo's review, a
nulldelay threw on the first hover. - Keep GlTooltip's engine instance out of Vue's reactivity: from Duo's
review. Vue 3's reactive proxy kept every destroyed
GlTooltipin the engine's registry. - Mark the tooltip breaking changes as BREAKING CHANGE: the changelog
convention for BootstrapVue removals, plus a note on the untranspiled
distsyntax. - Remove the vendored bootstrap-vue tooltip styles: dead since the new tooltip; the built CSS is unchanged.
- Update an existing tooltip when the directive is bound again: so
gitlab-org/gitlab's
v-tooltip-on-truncateno longer closes an open tooltip on every update. - Do not show GlTooltip with empty content: as
BTooltipdid, 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::tooltipcall sites behindshowGlTooltip/hideGlTooltiphelpers (!264610). The integration MR points those helpers at the new exports and deletes the two constants. - Update feature specs to the new
.gl-tooltipmarkup (!262798). - Hide tooltips on
mouseleaverather thanmouseout(!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::tooltiproot 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/hideGlTooltipfrom@gitlab/uidirectly, drop the helpers module, and remove the now-deadcontainer/boundaryplumbing intooltips.vue. - In gitlab-org/gitlab: remove the
.viewport/.windowmodifiers (about 70 files) and theboundary/containerkeys ofv-gl-tooltipvalues, which the new directive ignores. - With the
GlPopovermigration: hide open tooltips and popovers when the page goes into the back/forward cache, in one place (gitlab#604140). Today only popovers get that, throughtooltip_mixin.js. - The open "potential follow-up" threads below (the
$onusage intooltip.vue, thePLACEMENTSintooltip_engine.js), as follow-up issues.
Edited by Vanessa Otto