Tooltips: sphinx-hoverxref popup implementation

[agjohnson]

I couldn't find an issue where we talked about this specifically, but it has come up in a few calls.

The problem we have currently with hoverxref is that the popup library implementation needs to be replaced as we port it to an addon. I believe the issue here was that the library was a jQuery library? @humitos is this correct?

Options we should weigh:

• Load jQuery and library conditionally, via dynamic webpack import. We still use jQuery in this case, but only when the documentation project uses hoverxref
• We replace the library with another implementation
• We rely on upcoming HTML features that aren't yet fully standard ¹

Footnotes

1. The HTML popover attribute is upcoming, and is currently part of Interop 2024. Firefox is the outlier here currently, though there is an implementation in nightly. A hybrid approach would be to do a polyfill or something similar for unsupported browsers. ↩

[humitos]

I believe the issue here was that the library was a jQuery library? @humitos is this correct?

Yes, and it's because it's not maintained anymore. The last commit was 4 years ago: https://github.com/calebjacob/tooltipster

Load jQuery and library conditionally, via dynamic webpack import. We still use jQuery in this case, but only when the documentation project uses hoverxref

I would avoid this approach if possible because the underlying library is not well maintained anyways. We will either, replace the library now or in the future anyways. So, I wouldn't re-implement it using an old library at this point.

We replace the library with another implementation

This is the path I was following. I found popper.js which looked promising, and then found tippy.js which is another layer on top of popper.js that makes it easy to work (my POC lives at https://github.com/readthedocs/addons/blob/main/src/tooltips.js)

Today I found that popper.js was renamed to floating-ui (https://floating-ui.com/). So, it's worth to take another look at it. It's also worth to note that I didn't find any issue with these libraries and I had something that worked, but it wasn't just styled properly. Example:

We rely on upcoming HTML features that aren't yet fully standard

Hrm, it doesn't seem this is gonna happen soon, tho.

[agjohnson]

Hrm, it doesn't seem this is gonna happen soon, tho.

Most browsers already have this feature actually ¹ -- Firefox is the outlier here, it's only in nightly right now.

I feel like our time frame for this feature is still a little ways out, perhaps after we get a wider distribution on the current work in addons? So, time frames might even align too.

That is, we might not have to drop the work we have here already, and instead could use our current dependency until we swap to native only. Or do some polyfill if the native feature is missing and back down to the current library.

My main concern is reworking our dependency here twice. I think we should ultimately land on using native features if we can. Investing in a secondary intermediate dependency doesn't feel super useful for that.

If floating-ui has plans to act as a popover polyfill, that would be exactly what we need. I'm not familiar with the library though.

Footnotes

1. https://caniuse.com/?search=popover ↩