refactor notes to use floating-ui

[sujato]

terminology

Let us use "notes" to include both "comments" and "variants".

background

Bilara texts have support for notes as "comments" (on translations) and "variants" (on root texts).

These are implemented using a pure html/css approach. I did this because of a lack of tooltip elements in material web components, and because I couldn't see an elegant solution in third-party libraries. They were all too big and not what we wanted.

There are, however, a number of problems with this approach:

• each note has to be inserted twice, once as data-tooltip, once as span content.
• the data-tooltip version must be stripped of any HTML, which adds complexity to the process and limits usefulness (you can't link to texts, for example.)
• it's not great for accessibility.
• it's brittle and a simple CSS change can easily disrupt the whole thing.

possible solution

The most widely used tooltip library is popperjs. The author of popper is releasing a new library that looks ideal for our case: Floating-UI

https://www.floating-ui.com/docs/motivation

Rather than a simple tooltip idea, this exposes an API for positioning floating elements, thus it may be ideal for us to display notes in different forms. Using this approach, we can possibly mitigate all the problems outlined above.

• small (about 10kb gzipped)
• modern, tree-shakeable code: add features as you need
• use just one set of content for sidenotes and tooltips

https://github.com/floating-ui/floating-ui/

aims

The implementation would aim for essentially the same outcomes as the current implementation, but obviously solving the problems listed above. It would aim to be small. It should use the existing HTML structure. (It is possible to change this of course, but I would rather not.)

• Insert content only once (as span content).
• render HTML
• test for accessibility (maybe add ARIA?)
• tooltips should be positioned properly relative to viewport (test on mobile, etc., and also when viewport is changed)
• on mobiles, would it be best to display the tooltip at the bottom of the screen?
• there should be a mechanism to hold the displayed tooltip so links on it can be opened. Perhaps hold ctrl while hovering?
• tooltip anchor should be positioned properly (i.e. with a space after not a space before as currently)
• test tooltip anchor for visibility
• when the window is narrowed, the sidenotes become inline notes (as currently)
• do not display anything if note is empty (currently a stub is displayed)
• collapse sidenotes column if there are no notes (currently fixed width)
• tooltip should replace not only text notes, but all uses of title attribute on SC where they may be.

styles

Generally the styles should remain similar to what they are now, unless there is reason to change. We could introduce some animation for fluidity, remembering to respect prefers-reduced-motion.

[werenike]

Note that Floating UI does not in fact feature automatic collision avoidance (yet). The docs say the following (linking to this issue):

[sujato]

I just checked back with this issue, and, randomly, as of 12 hours ago the author has started working on this!

floating-ui/floating-ui#1440 (comment)

[Codigo-Fuentes]

@sujato hey, gonna take a look this weekend.

[sujato]

I've updated this to remove the problem of sidenotes, we are now handling them much more simply in CSS.