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

github-actions[bot] · Copilot · dsyme · web-flow · commit a7b9e556d35d · 2026-03-10T14:21:34.000+01:00
* Use Popover API for tooltip divs; fix scroll-offset positioning bug - Add `popover` attribute to `div.fsdocs-tip` elements in HtmlFormatting.fs, placing them in the browser top layer when supported (Baseline 2024). - Update fsdocs-tips.js to call showPopover()/hidePopover() on browsers that support the Popover API; fall back to display:block/none on older browsers. - Switch to `position: fixed` in the Popover API path (correct for top-layer elements) and fix a scroll-offset bug where tooltips appeared at wrong positions when the page was scrolled. - Fix a minor bug in the right-edge overflow correction (was using `y` instead of `x` as the base for the left-shift calculation). - Add `div.fsdocs-tip:popover-open { display: block }` to fsdocs-default.css so author-level display:none does not suppress the Popover API reveal. - Update RELEASE_NOTES.md. Closes #422 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: trigger CI checks * fix: resolve popover black-background regression; drop fallback; add fade-in - CSS: add `inset: unset` to `div.fsdocs-tip:popover-open` to reset the UA popover stylesheet's `inset: 0` (i.e. right:0 / bottom:0), which was stretching the element across the viewport and causing the visible dark area around the tooltip. - CSS: add `position: fixed` explicitly in the :popover-open rule so the element is correctly anchored to the JS-supplied left/top coordinates. - CSS: add a 120ms ease-out opacity fade-in animation for a subtle reveal. - JS: remove the display-toggle fallback branch entirely. The Popover API is Baseline 2024 (Chrome 114+, Firefox 125+, Safari 17+) and the technical audience of fsdocs users will have modern browsers. - RELEASE_NOTES: update entry to reflect the simplified (no-fallback) design and the animation addition. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: trigger checks * fix: replace onmouseout/onmouseover with data-* attrs + event delegation; fix Chrome popover background - HtmlFormatting.fs: emit data-fsdocs-tip / data-fsdocs-tip-unique instead of inline onmouseover/onmouseout handlers; overlapping vs non-overlapping cases now produce identical output (owner param is no longer needed) - GenerateHtml.fs (ApiDocs): same data-* attrs on code elements; add the popover attribute to fsdocs-tip divs so showPopover() works there too - fsdocs-tips.js: add delegated mouseover/mouseout listeners that read data-fsdocs-tip attributes; wrap showPopover() in try/catch for safety; keep showTip/hideTip on window for backward-compat with cached docs - fsdocs-default.css: add explicit background-color inside :popover-open to override Chrome UA top-layer canvas default (fixes black background); add [data-fsdocs-tip] cursor rule alongside legacy span[onmouseout] Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: trigger checks * Fix backdrop * Tweak css * Code cleanup * fix: update test assertion to match new data-fsdocs-tip attribute convention The ConvertCommand test checked that 'fsdocs-tip' is not in the output when no template is given. Since the span elements now use data-fsdocs-tip attributes (instead of onmouseover/onmouseout inline handlers), the output always contains 'fsdocs-tip' as part of the attribute name. The test intent is to verify that tooltip *div* elements (class="fsdocs-tip") are not emitted without a template. Update the assertion to check for class="fsdocs-tip" specifically, which only matches the tooltip divs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: trigger checks --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Don Syme <dsyme@users.noreply.github.com> Co-authored-by: nojaf <florian.verdonck@outlook.com>
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -2,17 +2,15 @@
 
 ## [Unreleased]
 
-### Refactored
-* Split `MarkdownParser.fs` (1500 lines) into `MarkdownInlineParser.fs` (inline formatting) and `MarkdownParser.fs` (block-level parsing) for better maintainability. [#1022](https://github.com/fsprojects/FSharp.Formatting/issues/1022)
-* Split pipe-table and Emacs-table parsing out of `MarkdownBlockParser.fs` into a new `MarkdownTableParser.fs` (196 lines), reducing `MarkdownBlockParser.fs` from 958 to 760 lines. [#1022](https://github.com/fsprojects/FSharp.Formatting/issues/1022)
-
 ### Added
 * Add `dotnet fsdocs convert` command to convert a single `.md`, `.fsx`, or `.ipynb` file to HTML (or another output format) without building a full documentation site. [#811](https://github.com/fsprojects/FSharp.Formatting/issues/811)
 * `fsdocs convert` now accepts the input file as a positional argument (e.g. `fsdocs convert notebook.ipynb -o notebook.html`). [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 * `fsdocs convert` infers the output format from the output file extension when `--outputformat` is not specified (e.g. `-o out.md` implies `--outputformat markdown`). [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 * `fsdocs convert` now accepts `-o` as a shorthand for `--output`. [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 
 ### Changed
+* Tooltip elements (`div.fsdocs-tip`) now use the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) (Baseline 2024: Chrome 114+, Firefox 125+, Safari 17+). Tooltips are placed in the browser's top layer — no `z-index` needed, always above all other content. Fixes a positioning bug where tooltips appeared offset when the page was scrolled. The previous `display`-toggle fallback has been removed. Tooltips also fade in with a subtle animation. [#422](https://github.com/fsprojects/FSharp.Formatting/issues/422), [#1061](https://github.com/fsprojects/FSharp.Formatting/pull/1061)
+* Generated code tokens no longer use inline `onmouseover`/`onmouseout` event handlers. Tooltips are now triggered via `data-fsdocs-tip` / `data-fsdocs-tip-unique` attributes and a delegated event listener in `fsdocs-tips.js`. The `popover` attribute is also added to API-doc tooltip divs so they use the same top-layer path. [#1061](https://github.com/fsprojects/FSharp.Formatting/pull/1061)
 * Changed `range` fields in `MarkdownSpan` and `MarkdownParagraph` DU cases from `MarkdownRange option` to `MarkdownRange`, using `MarkdownRange.zero` as the default/placeholder value instead of `None`.
 * When no template is provided (e.g. `fsdocs convert` without `--template`), `fsdocs-tip` tooltip divs are no longer included in the output. Tooltips require JavaScript/CSS from a template to function, so omitting them produces cleaner raw output. [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 
diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css
@@ -983,8 +983,6 @@ table.pre, code, pre.fssnip {
 
 /* tooltips */
 div.fsdocs-tip {
-    z-index: 1000;
-    display: none;
     background-color: var(--doc-tip-background);
     border-radius: var(--radius);
     border: 1px solid var(--header-border);
@@ -993,16 +991,30 @@ div.fsdocs-tip {
     font-variant-ligatures: none;
     color: var(--code-color);
     box-shadow: 0 1px 1px var(--shadow-color);
+    margin: 0;
 
     & code {
         color: var(--code-color);
     }
 }
 
-span[onmouseout] {
+@keyframes fsdocs-tip-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+/* Reset UA inset so JS-supplied left/top control position. */
+div.fsdocs-tip:popover-open {
+    position: fixed;
+    inset: unset;
+    animation: fsdocs-tip-fade-in 120ms ease-out;
+}
+
+[data-fsdocs-tip] {
     cursor: pointer;
 }
 
+
 /* API docs */
 #content > div > h2:first-child {
     margin-top: 0;
@@ -1212,7 +1224,7 @@ span[onmouseout] {
 }
 
 /* Search */
-::backdrop {
+dialog::backdrop {
     background-color: #020202;
     opacity: 0.5;
 }
diff --git a/docs/content/fsdocs-tips.js b/docs/content/fsdocs-tips.js
@@ -1,19 +1,26 @@
 let currentTip = null;
 let currentTipElement = null;
 
-function hideTip(evt, name, unique) {
+function hideTip(name) {
     const el = document.getElementById(name);
-    el.style.display = "none";
+    if (el) {
+        try { el.hidePopover(); } catch (_) { }
+    }
     currentTip = null;
+    currentTipElement = null;
 }
 
-function hideUsingEsc(e) {
-    hideTip(e, currentTipElement, currentTip);
-}
-
-function showTip(evt, name, unique, owner) {
-    document.onkeydown = hideUsingEsc;
+function showTip(evt, name, unique) {
     if (currentTip === unique) return;
+
+    // Hide the previously shown tooltip before showing the new one
+    if (currentTipElement !== null) {
+        const prev = document.getElementById(currentTipElement);
+        if (prev) {
+            try { prev.hidePopover(); } catch (_) { }
+        }
+    }
+
     currentTip = unique;
     currentTipElement = name;
 
@@ -22,28 +29,45 @@ function showTip(evt, name, unique, owner) {
     let y = evt.clientY + offset;
 
     const el = document.getElementById(name);
-    el.style.position = "absolute";
-    el.style.display = "block";
-    el.style.left = `${x}px`;
-    el.style.top = `${y}px`;
     const maxWidth = document.documentElement.clientWidth - x - 16;
     el.style.maxWidth = `${maxWidth}px`;
+    el.style.left = `${x}px`;
+    el.style.top = `${y}px`;
+
+    try { el.showPopover(); } catch (_) { }
 
-    const rect =  el.getBoundingClientRect();
-    // Move tooltip if it is out of sight
-    if(rect.bottom > window.innerHeight) {
+    const rect = el.getBoundingClientRect();
+    // Move tooltip if it would appear outside the viewport
+    if (rect.bottom > window.innerHeight) {
         y = y - el.clientHeight - offset;
         el.style.top = `${y}px`;
     }
-
     if (rect.right > window.innerWidth) {
-        x = y - el.clientWidth - offset;
+        x = x - el.clientWidth - offset;
         el.style.left = `${x}px`;
-        const maxWidth = document.documentElement.clientWidth - x - 16;
-        el.style.maxWidth = `${maxWidth}px`;
+        el.style.maxWidth = `${document.documentElement.clientWidth - x - 16}px`;
     }
 }
 
+// Event delegation: trigger tooltips from data-fsdocs-tip attributes
+document.addEventListener('mouseover', function (evt) {
+    const target = evt.target.closest('[data-fsdocs-tip]');
+    if (!target) return;
+    const name = target.dataset.fsdocsTip;
+    const unique = parseInt(target.dataset.fsdocsTipUnique, 10);
+    showTip(evt, name, unique);
+});
+
+document.addEventListener('mouseout', function (evt) {
+    const target = evt.target.closest('[data-fsdocs-tip]');
+    if (!target) return;
+    // Only hide when the mouse has left the trigger element entirely
+    if (target.contains(evt.relatedTarget)) return;
+    const name = target.dataset.fsdocsTip;
+    const unique = parseInt(target.dataset.fsdocsTipUnique, 10);
+    hideTip(name);
+});
+
 function Clipboard_CopyTo(value) {
     if (navigator.clipboard) {
         navigator.clipboard.writeText(value);
@@ -57,7 +81,4 @@ function Clipboard_CopyTo(value) {
     }
 }
 
-window.showTip = showTip;
-window.hideTip = hideTip;
-// Used by API documentation
-window.Clipboard_CopyTo = Clipboard_CopyTo;
+window.Clipboard_CopyTo = Clipboard_CopyTo;
diff --git a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs
@@ -48,14 +48,9 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) =
         div [] [
             let id = UniqueID().ToString()
 
-            code
-                [
-                    OnMouseOut(sprintf "hideTip(event, '%s', %s)" id id)
-                    OnMouseOver(sprintf "showTip(event, '%s', %s)" id id)
-                ]
-                content
+            code [ Custom("data-fsdocs-tip", id); Custom("data-fsdocs-tip-unique", id) ] content
 
-            div [ Class "fsdocs-tip"; Id id ] tip
+            div [ Custom("popover", ""); Class "fsdocs-tip"; Id id ] tip
         ]
 
     let sourceLink url =
diff --git a/src/FSharp.Formatting.CodeFormat/HtmlFormatting.fs b/src/FSharp.Formatting.CodeFormat/HtmlFormatting.fs
@@ -23,8 +23,8 @@ type ToolTipFormatter(prefix) =
     let mutable count = 0
     let mutable uniqueId = 0
 
-    /// Formats tip and returns assignments for 'onmouseover' and 'onmouseout'
-    member x.FormatTip (tip: ToolTipSpans) overlapping formatFunction =
+    /// Formats tip and returns data attributes for tooltip triggering
+    member x.FormatTip (tip: ToolTipSpans) formatFunction =
         uniqueId <- uniqueId + 1
 
         let stringIndex =
@@ -34,32 +34,15 @@ type ToolTipFormatter(prefix) =
                 count <- count + 1
                 tips.Add(tip, (count, formatFunction tip))
                 count
-        // stringIndex is the index of the tool tip
-        // uniqueId is globally unique id of the occurrence
-        if overlapping then
-            // The <span> may contain other <span>, so we need to
-            // get the element and check where the mouse goes...
-            String.Format(
-                "id=\"{0}t{1}\" onmouseout=\"hideTip(event, '{0}{1}', {2})\" "
-                + "onmouseover=\"showTip(event, '{0}{1}', {2}, document.getElementById('{0}t{1}'))\" ",
-                prefix,
-                stringIndex,
-                uniqueId
-            )
-        else
-            String.Format(
-                "onmouseout=\"hideTip(event, '{0}{1}', {2})\" "
-                + "onmouseover=\"showTip(event, '{0}{1}', {2})\" ",
-                prefix,
-                stringIndex,
-                uniqueId
-            )
+        // stringIndex is the index of the tool tip div
+        // uniqueId is the globally unique id of this hover occurrence
+        String.Format("data-fsdocs-tip=\"{0}{1}\" data-fsdocs-tip-unique=\"{2}\" ", prefix, stringIndex, uniqueId)
 
 
     /// Returns all generated tool tip elements
     member x.WriteTipElements(writer: TextWriter) =
         for (KeyValue(_, (index, html))) in tips do
-            writer.WriteLine(sprintf "<div class=\"fsdocs-tip\" id=\"%s%d\">%s</div>" prefix index html)
+            writer.WriteLine(sprintf "<div popover class=\"fsdocs-tip\" id=\"%s%d\">%s</div>" prefix index html)
 
 
 /// Represents context used by the formatter
@@ -71,7 +54,7 @@ type FormattingContext =
       CloseTag: string
       OpenLinesTag: string
       CloseLinesTag: string
-      FormatTip: ToolTipSpans -> bool -> (ToolTipSpans -> string) -> string
+      FormatTip: ToolTipSpans -> (ToolTipSpans -> string) -> string
       TokenKindToCss: (TokenKind -> string) }
 
 // --------------------------------------------------------------------------------------
@@ -106,12 +89,12 @@ let rec formatTokenSpans (ctx: FormattingContext) =
         | TokenSpan.Error(_kind, message, body) when ctx.GenerateErrors ->
             let tip = ToolTipReader.formatMultilineString (message.Trim().Split('\n'))
 
-            let tipAttributes = ctx.FormatTip tip true formatToolTipSpans
+            let tipAttributes = ctx.FormatTip tip formatToolTipSpans
 
             ctx.Writer.Write("<span ")
             ctx.Writer.Write(tipAttributes)
             ctx.Writer.Write("class=\"cerr\">")
-            formatTokenSpans { ctx with FormatTip = fun _ _ _ -> "" } body
+            formatTokenSpans { ctx with FormatTip = fun _ _ -> "" } body
             ctx.Writer.Write("</span>")
 
         | TokenSpan.Error(_, _, body) -> formatTokenSpans ctx body
@@ -124,7 +107,7 @@ let rec formatTokenSpans (ctx: FormattingContext) =
         | TokenSpan.Omitted(body, hidden) ->
             let tip = ToolTipReader.formatMultilineString (hidden.Trim().Split('\n'))
 
-            let tipAttributes = ctx.FormatTip tip true formatToolTipSpans
+            let tipAttributes = ctx.FormatTip tip formatToolTipSpans
 
             ctx.Writer.Write("<span ")
             ctx.Writer.Write(tipAttributes)
@@ -136,7 +119,7 @@ let rec formatTokenSpans (ctx: FormattingContext) =
             // Generate additional attributes for ToolTip
             let tipAttributes =
                 match tip with
-                | Some(tip) -> ctx.FormatTip tip false formatToolTipSpans
+                | Some(tip) -> ctx.FormatTip tip formatToolTipSpans
                 | _ -> ""
 
             // Get CSS class name of the token
diff --git a/tests/fsdocs-tool.Tests/ConvertCommandTests.fs b/tests/fsdocs-tool.Tests/ConvertCommandTests.fs
@@ -66,7 +66,9 @@ let ``ConvertCommand omits fsdocs-tip divs when no template given`` () =
 
     result |> shouldEqual 0
     let html = File.ReadAllText(outputFile)
-    html |> shouldNotContainText "fsdocs-tip"
+    // Tooltip trigger spans use data-fsdocs-tip attributes; the assertion checks that
+    // the tooltip *div* elements (class="fsdocs-tip") are NOT emitted without a template.
+    html |> shouldNotContainText "class=\"fsdocs-tip\""
 
 [<Test>]
 let ``ConvertCommand converts .ipynb file to HTML`` () =
