[Repo Assist] Use Popover API for code snippet tooltips; fix scroll-offset positioning

[github-actions]

🤖 This PR was created by Repo Assist, an automated AI assistant.

Closes #422

Summary

Migrates hover tooltips (the div.fsdocs-tip elements shown when hovering over syntax tokens in code blocks) to use the browser-native [Popover API]((developer.mozilla.org/redacted), with a clean fallback for older browsers.

Changes

src/FSharp.Formatting.CodeFormat/HtmlFormatting.fs

Add the popover attribute to every generated div.fsdocs-tip element:

(div class="fsdocs-tip" id="fstips3")...(/div)

(div popover class="fsdocs-tip" id="fstips3")...(/div)

docs/content/fsdocs-tips.js

• Popover API path (modern browsers, Baseline 2024): set position: fixed, then call el.showPopover() / el.hidePopover(). Elements in the top layer are always rendered above all other page content — no z-index arithmetic needed.
• Fallback path (older browsers): retain existing position: absolute + display: block/none behaviour unchanged.
• Bug fix: the right-edge overflow correction used y instead of x as the base for the left-shift; corrected to x.
• Bug fix: currentTipElement was never cleared on hide; now set to null together with currentTip.

docs/content/fsdocs-default.css

Add div.fsdocs-tip:popover-open { display: block; } so the author-level display: none rule does not suppress the Popover API reveal (author rules take precedence over UA rules in the cascade). Also add margin: 0 to prevent UA default popover margins from shifting the tooltip.

Why the Popover API?

Property	Old (JS absolute positioning)	New (Popover API)
Rendering layer	Normal stacking context — needs z-index: 1000	Browser top layer — always above everything
Positioning on scroll	Bug: clientX/Y used with position: absolute → offset when scrolled	Correct: clientX/Y used with position: fixed in top layer
Keyboard dismiss	Manual document.onkeydown handler	Built-in Escape key handling for auto popovers
Browser support	All	[Baseline 2024]((developer.mozilla.org/redacted) (Chrome 114+, Firefox 125+, Safari 17+)

Test Status

• ✅ Build: dotnet build src/FSharp.Formatting.CodeFormat/ — 0 warnings, 0 errors
• ✅ Tests: dotnet test tests/FSharp.CodeFormat.Tests/ — 20 passed, 2 skipped (pre-existing infrastructure skips)
• ✅ Formatting: Fantomas check on changed .fs file — no changes needed
• ⚠️ Visual verification: manual testing of hover tooltips, light-dismiss (Escape), and scroll-position accuracy recommended before merge

Generated by Repo Assist for issue #422

Generated by Repo Assist

To install this agentic workflow, run

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

[nojaf]

/repo-assist there is a regression here. When using the popover api, I see a black background on the surrounding tooltip area.

I also wonder if we need to stay backwards compatible here? Giving our technical audience the popover api will be present in high numbers. I don't think it is worth having the two mechanisms.

Also, improve to popup to have a very subtle fade in animation.

[github-actions]

Commit pushed: 95f9b91

Generated by Repo Assist

[nojaf]

/repo-assist the black background is not fixed for me in latest Chrome.

I also wonder if we still need the more archaic code generated in

<span onmouseout="hideTip(event, 'fs1', 1)" onmouseover="showTip(event, 'fs1', 1)" class="fn">helloWorld</span>

onmouseout and onmouseover to trigger popover feels like fighting the modern api.
Is there no better way to do this? Modify the generated html if you must.

[github-actions]

Commit pushed: c4f034a

Generated by Repo Assist

[github-actions]

🤖 Repo Assist here — I've just pushed a follow-up commit addressing both points.

What changed

Black background in Chrome (:popover-open)

Chrome's UA stylesheet sets background-color: canvas on the top-layer element. Even though author rules should win, the canvas keyword can resolve unexpectedly in Chrome's top layer when color-scheme is involved. The fix is to repeat background-color: var(--doc-tip-background) explicitly inside div.fsdocs-tip:popover-open so there's no ambiguity.

No more onmouseover / onmouseout inline handlers

Generated HTML (HtmlFormatting.fs and GenerateHtml.fs) now emits:

<span data-fsdocs-tip="fs1" data-fsdocs-tip-unique="1" class="fn">helloWorld</span>

instead of the old inline handlers. A single delegated listener in fsdocs-tips.js picks these up:

document.addEventListener('mouseover', evt => {
    const target = evt.target.closest('[data-fsdocs-tip]');
    if (!target) return;
    showTip(evt, target.dataset.fsdocsTip, +target.dataset.fsdocsTipUnique);
});

The mouseout handler checks target.contains(evt.relatedTarget) before hiding, so moving between a trigger and its children doesn't flicker.

showTip now wraps showPopover() in a try/catch so old cached HTML (which still carries inline handlers) and API-doc tooltips won't throw if something's off. window.showTip/window.hideTip are still exported for backward compat.

API-doc tooltip divs (GenerateHtml.fs) now carry the popover attribute — previously missing, which would have caused showPopover() to throw a DOMException for every API doc hover.

Generated by Repo Assist for issue #1061 · ◷

To install this agentic workflow, run

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