CSS tooltips as an alternative (or replacement) for JS tooltips

[cloudRoutine]

CSS tooltips would make snippets generated by FSharp.Formatting usable in contexts where js execution is restricted. I think they would also simplify and cut down the size of the generated html pages

<div>
  Let's pretend like this is src code</br>
</br>
<code> Array.<span class="tooltip ts mapfn" >map</span></code>
</div>

.tooltip {
    position: relative;
    display: inline-block;
}

.tooltip.ts:hover::before{
  visibility: visible;
  border-style: solid;
  display: block;
  padding: 4px 8px;
  position: absolute;
  left: 0;
  bottom: 100%;
  white-space: pre;
  background-color: #000;
  color: #fff; 
}

.tooltip.ts.mapfn:hover::before { 
  content: 'you map arrays, \a what did you think? \a ;P';
}

(^ play with this example)

the CSS pseudo classes make it easy to reuse tooltips at multiple points in the same snippet, and nothing as verbose as

<span onmouseout="hideTip(event, 'fs116', 445)" onmouseover="showTip(event, 'fs116', 445)" class="i">

would be needed anymore.

I'm no CSS expert, so there may be a more elegant way to implement this functionality.

[tpetricek]

I'd be happy with this change, provided that it works on reasonable number of modern browsers (which I suspect it does).

[cloudRoutine]

This good enough? 😉

[tpetricek]

Looks good.

The CSS solution could be more reliable too - the JS code behaved oddly when the parent elements are relative, absolute, etc. So, this needs some testing in the new version too.

[github-actions]

🤖 This is an automated response from Repo Assist.

Reviving this thread with a technical note, since this issue also relates to the tooltip jitter bug in #679.

Current implementation (how it works today)

Tooltip content is stored in hidden div.fsdocs-tip elements at the end of the generated HTML. tips.js positions and reveals them using JS-computed absolute coordinates (iterating offsetParent chain in findPos). That layout-reflow loop is the root cause of the stuttering in #679.

Why pure CSS is non-trivial here

Classic CSS :hover tooltips (:hover + .tooltip { visibility: visible }) require the tooltip element to be a sibling or descendant of the trigger element. Today, each tooltip (div id="tipN") is detached from its trigger <span onmouseover="showTip(...)"> — they're in completely different parts of the DOM. Migrating to CSS positioning would require restructuring the HTML generator (in CodeFormatAgent.fs / CodeFormat.fs) to emit tooltip content adjacent to each trigger span.

A feasible hybrid approach

1. In the HTML generator, move each tooltip (div) to be an immediate next sibling of its <span> trigger (wrapping them in <span class="tooltip-host"> if needed).
2. Replace div.fsdocs-tip { display: none } + JS el.style.display = "block" with CSS visibility: hidden + :hover > .fsdocs-tip { visibility: visible; position: absolute; ... }.
3. Remove or greatly simplify tips.js — no more JS coordinate calculation.

This would fix #679, work without JS, and eliminate the reflow loop. The tooltip content is already rich HTML (multi-line, syntax-coloured), so content: attr(data-*) is not an option — the adjacent-sibling HTML restructuring approach is the right path.

Would a PR implementing the HTML restructuring + CSS-only tooltip positioning be welcome? Happy to attempt it if there is maintainer interest.

Generated by Repo Assist

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@828ac109efb43990f59475cbfce90ede5546586c. View source at https://github.com/githubnext/agentics/tree/828ac109efb43990f59475cbfce90ede5546586c/workflows/repo-assist.md.

[dsyme]

Would a PR implementing the HTML restructuring + CSS-only tooltip positioning be welcome? Happy to attempt it if there is maintainer interest.

Yes Repo Assist it would be of interest

[nojaf]

The real answer here would be to use https://developer.mozilla.org/en-US/docs/Web/API/Popover_API
But still a bit new browser API.

[github-actions]

🤖 This is an automated response from Repo Assist.

Following up on @dsyme's confirmation of interest and @nojaf's mention of the Popover API — I've opened a draft PR implementing the Popover API approach:

PR: Use Popover API for code snippet tooltips; fix scroll-offset positioning

What it does

• Adds popover attribute to every div.fsdocs-tip element generated by HtmlFormatting.fs, placing them in the browser [top layer]((developer.mozilla.org/redacted) on modern browsers.
• Updates fsdocs-tips.js to call showPopover() / hidePopover() when available (graceful fallback to display: block/none for older browsers).
• Switches to position: fixed in the Popover API path — this is correct for top-layer elements and also fixes the existing scroll-offset bug where tooltips appeared offset from the cursor when the page was scrolled.
• All existing tests pass; no API changes.

Note on the Popover API vs. full CSS-only

The Popover API still requires a small amount of JS to:

1. Position the popover near the cursor on mouseover, and
2. Call showPopover() / hidePopover().

A fully CSS-only tooltip (zero JS) would require restructuring the generated HTML so each tooltip div is a sibling of its trigger span, enabling CSS :hover + adjacent sibling rules. That's a larger change. The Popover API approach gives most of the benefits (top-layer rendering, proper Escape dismiss, accessibility) with minimal code changes.

Generated by Repo Assist

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@da02dddebe71d9a937665abdcd1f5214dab852a7