Tooltip discovery

[zarahzachz]

WNMGDS-2708

This is a discovery to see how far we can get in crafting native tooltips. Spoiler alert: It's pretty dang far!

But first...

Why are we even doing this?

Our current implementation of Tooltip requires the use of at least three separate libraries to handle different functionalities (react-transition-group, focus-trap-react, and popperjs). Not only do these libraries add to our bundle size (impacting performance) but they're also ONLY used for this one component. That's a hefty fee for something that's not that reusable.

(At this point I should also point out that react-transition-group has a comment that it needs to be updated once the React peer dependency's been resolved. This was due to some Astro SSR stuff in #2961)

By leaning as hard as we can on native web API, we can eliminate most (if not all) of these additional libraries with minimal impact on UX.

Aside from making sick gains, our Tooltips have historically had... issues. The big ones include:

• Our API supports links and "other elements" as tooltip triggers
  • Links shouldn't be used as tooltip triggers as they "go places," they don't "do things"
  • "Other elements" was probably added to include support for input type="button", but this caveat feels outdated at this point
  • Buttons should be the only element that opens a tooltip (but button has design implications, see point below)
• Our UX is far too varied, leading to confusion on how to use each design
  • This leads to questions about "styling <button> as a link" so it flows inline with text (buttons can't do this)
  • We once had a request to make a tooltip also navigate to another page (I think this was for glossary functionality?)
  • Using dialog tooltips isn't really making these tooltips a dialog element
    • Creates separate UX for keyboard and screenreader users (screenreader users can navigate entire document if open, keyboard users are trapped)
    • Dialog tooltips have ancillary props to be toggled on/off (like those for the close button)

As I pointed out earlier, using the native Popover API would result in minimal impact on UX - meaning UX would change, but in a way that solves these UX issues (by standardizing tooltip behavior to open on click [aka, persisting mobile UX across viewports], correctly implementing a11y, and allowing us to officially remove link support from this component).

Watch your six!

The Popover API is easy and straightforward to use, however there are some foot-guns.

• One of the attributes used (popovertarget) is already being deprecated in favor of a new one (invoketarget)
  • Despite the deprecation, I went with popovertarget because it has better browser support
  • There is a Popover polyfill from Oddbird (I think one of their engineers made the official Popover spec), but didn't run into a need for this so I didn't try it out
  • I think the Oddbird polyfill just provides more support for the invoketarget attribute but I'm not certain
• React types don't understand the new HTML attributes, so TS builds break
  • This is why Tooltip was committed as a JSX file and not TSX
  • As a result, I couldn't easily use our pre-built Button and CloseButton components without breaking builds, so some finessing is still needed in this area
  • Another gotcha was the popover attribute. All specs/instructions say just applying this attribute will create a "popover" element, but I found I still had to assign it a value of "auto" for it to work. I think this is also related to React not understanding the attributes (it kept inferring it was a boolean, which resulted in no tooltips rendering)
• Popover API doesn't include the ability to position the element
  • Only positioning allowed is absolute positioning within the context of the browser (possibly due to the top-layerness of it all)
  • The Anchor Positioning API is meant to solve for this half of the popover equation, but the spec is still very drafty
    • Despite Oddbird having an Anchor Positioning polyfill, I don't know how helpful it'd be to use with the spec being up in the air
  • Floating-UI seems like a fine compromise in positioning tooltips (you can just import the positioning library) and it comes with its own intersection observer as well
• Minor annoyance, but I kept accidentally typing "poopover" 💩

As far as support goes...

• popover and its associated attributes has pretty good support, with all browsers supporting it (FF being the latest to adopt)
• Invokers are only supported behind flags, but once adopted we'll want to do cleanup work to make sure we're using the non-deprecated attributes if we go down this route

Wins

• I was able to remove 4 JS libraries (while installing 1)
  • I didn't do a proper comparison, but looking at the dist bundle for React after all was said and done it was 2.2MB - is this better or worse?
  • All libraries removed were ONLY used for tooltips, so removing them felt very nice indeed
• (This is quasi-win-ish) I drastically reduced the code written for the Tooltip itself
  • CSS
    • The amount of CSS needed was hacked to pieces
    • We really only need to style the tooltip itself and the location of the close button within
    • Will probably need better styling for the inline tooltip trigger button, but that should be minimal
  • JS (this is where it's tough to say if we truly reduced code)
    • As mentioned, TS choked on the new attributes so I had to save the component as a JSX
    • No TSX meant I couldn't reuse some of our Button components, so it could very well be smaller
    • Many props were removed, some will need to be reimplemented (like classnames)
    • The Floating-UI implementation will probably need to be expanded upon to allow for prop overrides comparable to the original Tooltip implementation (more on this below)
• The new API removes our problematic anchor tags as tooltip trigger, so we now only have block and inline tooltips

Observations and next steps

Observations

It behooves us to re-evaluate our current Tooltip implementation before updating the codebase. I found myself scratching my head at the quantity of customizations we allow for tooltips and wonder if this was a case of over-optimization? I'm not sure how many of these props are actually being used (e.g., interactiveBorder, transitionDuration, inversed, etc.), but it seems similar to what we saw when updating our dialogs in that we probably offer way too much stuff. And if we're rolling out a new Tooltip, does it make sense to reimplement stuff we don't need?

We should probably lock-in the non-negotiable features (like maxWidth, animations, etc.) and just let users adjust the default position (top, bottom, left, right), but that's just my two cents.

Next steps

• Need to confirm desired component API
• Need to update types to use TS
  • Discussed with Patrick and we can probably skirt the TS issue by manually adding global interfaces (like we did for web components)
• Need to write new tests
  • We may need to add the popover polyfill just for testing purposes (similar to our issues with <dialog>), but with the popover API being attributes and not a new element, maybe not)
• Need to update markup to use prebuilt components
• Need to test with a11y
  • I tested locally and it seems to work really well (better than our current tooltip in some cases)
    • Our interactive tooltip has focus trapping in it that doesn't render the non-tooltip stuff inert, so keyboard users get trapped inside the tooltip (with no visual cues like dimmed backdrop indicating its a modal) and screenreader users can access things outside the tooltip with the virtual cursor
  • a11y advocates haven't raised the alarm on popover outside of a small bug in how popover video works (it continues to play even when dismissed)
  • Hidde's blog has a good breakdown on the differences between dialogs and popovers and includes some code examples on how to best use either API to build what we're looking for
• Need to implement animation CSS
• Need to implement the tooltip "tail"
  • I only just realized this was missing while writing this PR, but Floating-UI has a method for this we could probably use

[zarahzachz]

Should evaluate this style when doing Tooltip work

[pwolfert]

Adding this here because it looks like GitHub didn't automatically pick up on the reference: Discovery branch