feat: add glossary tooltip

Author: schultek

site/lib/_sass/_site.scss

@@ -38,6 +38,7 @@
 @use 'components/tags';
 @use 'components/theming';
 @use 'components/toc';
+@use 'components/tooltip';
 @use 'components/trailing';
 
 @use 'pages/dash';

site/lib/_sass/components/_glossary.scss

@@ -13,6 +13,7 @@ body.glossary-page main {
       min-height: 8rem;
 
       .initial-content {
+
         // Only show the first paragraph if collapsed.
         > :not(:first-child) {
           display: none;
@@ -29,7 +30,9 @@ body.glossary-page main {
     }
 
     .expand-button {
-      &:hover, &:focus-within {
+
+      &:hover,
+      &:focus-within {
         transition: transform .25s ease-out;
       }
     }
@@ -61,7 +64,8 @@ body.glossary-page main {
     }
   }
 
-  .initial-content, .expandable-content {
+  .initial-content,
+  .expandable-content {
     > :first-child {
       margin-top: 0;
     }
@@ -77,4 +81,4 @@ body.glossary-page main {
     align-items: center;
     gap: 0.25rem;
   }
-}
+}

site/lib/_sass/components/_tooltip.scss

@@ -0,0 +1,57 @@
+.tooltip-wrapper {
+    position: relative;
+
+    a.tooltip-target {
+        color: inherit;
+        text-decoration: underline dotted;
+    }
+
+    .tooltip {
+        visibility: hidden;
+
+        display: flex;
+        position: absolute;
+        z-index: 100;
+        top: 100%;
+        left: 50%;
+        transform: translateX(-50%);
+
+        flex-flow: column nowrap;
+        width: 250px;
+
+        background: var(--site-raised-bgColor);
+        border: 0.05rem solid rgba(0, 0, 0, .125);
+        border-radius: 0.75rem;
+        box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, .15);
+        padding: 0.8rem;
+
+        .tooltip-header {
+            font-size: 1.2rem;
+            font-weight: 500;
+            margin-bottom: 0.25rem;
+        }
+
+        .tooltip-content {
+            font-size: 0.875rem;
+            color: var(--site-secondary-textColor);
+        }
+    }
+
+    // On non-touch devices, show tooltip on hover or focus.
+    @media all and not (pointer: coarse) {
+        &:hover .tooltip {
+            visibility: visible;
+        }
+
+        &:has(.tooltip-target:focus) .tooltip {
+            visibility: visible;
+        }
+    }
+
+    // On touch devices, show tooltip on click (see global_scripts.dart).
+    @media all and (pointer: coarse) {
+        .tooltip.visible {
+            visibility: visible;
+        }
+    }
+}

site/lib/src/client/global_scripts.dart

@@ -46,6 +46,7 @@ void _setUpSite() {
   _setUpExpandableCards();
   _setUpTableOfContents();
   _setUpReleaseTags();
+  _setUpTooltips();
 }
 
 void _setUpSidenav() {
@@ -543,3 +544,93 @@ void _setUpReleaseTags() {
   fetchVersion('beta');
   fetchVersion('dev');
 }
+
+void _setUpTooltips() {
+  final tooltipWrappers = web.document.querySelectorAll('.tooltip-wrapper');
+
+  final isTouchscreen = web.window.matchMedia('(pointer: coarse)').matches;
+
+  void setup(bool setUpClickListener) {
+    for (var i = 0; i < tooltipWrappers.length; i++) {
+      final linkWrapper = tooltipWrappers.item(i) as web.HTMLElement;
+      final target = linkWrapper.querySelector('.tooltip-target');
+      final tooltip = linkWrapper.querySelector('.tooltip') as web.HTMLElement?;
+
+      if (target == null || tooltip == null) {
+        continue;
+      }
+      _ensureVisible(tooltip);
+
+      if (setUpClickListener && isTouchscreen) {
+        // On touchscreen devices, toggle tooltip visibility on tap.
+        target.addEventListener(
+          'click',
+          ((web.Event e) {
+            final isVisible = tooltip.classList.contains('visible');
+            if (isVisible) {
+              tooltip.classList.remove('visible');
+            } else {
+              tooltip.classList.add('visible');
+            }
+            e.preventDefault();
+          }).toJS,
+        );
+      }
+    }
+  }
+
+  void closeAll() {
+    final visibleTooltips = web.document.querySelectorAll(
+      '.tooltip.visible',
+    );
+    for (var i = 0; i < visibleTooltips.length; i++) {
+      final tooltip = visibleTooltips.item(i) as web.HTMLElement;
+      tooltip.classList.remove('visible');
+    }
+  }
+
+  setup(true);
+
+  // Reposition tooltips on window resize.
+  web.EventStreamProviders.resizeEvent.forTarget(web.window).listen((_) {
+    setup(false);
+  });
+
+  // Close tooltips when clicking outside of any tooltip wrapper.
+  web.EventStreamProviders.clickEvent.forTarget(web.document).listen((e) {
+    if ((e.target as web.Element).closest('.tooltip-wrapper') == null) {
+      closeAll();
+    }
+  });
+
+  // On touchscreen devices, close tooltips when scrolling.
+  if (isTouchscreen) {
+    web.EventStreamProviders.scrollEvent.forTarget(web.window).listen((_) {
+      closeAll();
+    });
+  }
+}
+
+/// Adjust the tooltip position to ensure it is fully inside the
+/// ancestor .content element.
+void _ensureVisible(web.HTMLElement tooltip) {
+  final containerRect = tooltip.closest('.content')!.getBoundingClientRect();
+  final tooltipRect = tooltip.getBoundingClientRect();
+  final offset = double.parse(tooltip.getAttribute('data-adjusted') ?? '0');
+
+  final tooltipLeft = tooltipRect.left - offset;
+  final tooltipRight = tooltipRect.right - offset;
+
+  if (tooltipLeft < containerRect.left) {
+    final offset = containerRect.left - tooltipLeft;
+    tooltip.style.left = 'calc(50% + ${offset}px)';
+    tooltip.dataset['adjusted'] = offset.toString();
+  } else if (tooltipRight > containerRect.right) {
+    final offset = tooltipRight - containerRect.right;
+    tooltip.style.left = 'calc(50% - ${offset}px)';
+    tooltip.dataset['adjusted'] = (-offset).toString();
+  } else {
+    tooltip.style.left = '50%';
+    tooltip.dataset['adjusted'] = '0';
+  }
+}

site/lib/src/extensions/glossary_link_processor.dart

@@ -0,0 +1,89 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:jaspr/jaspr.dart';
+import 'package:jaspr_content/jaspr_content.dart';
+
+import '../pages/glossary.dart';
+
+/// A node-processing, page extension for Jaspr Content that looks for links to
+/// glossary entries and enhances them with interactive glossary tooltips.
+class GlossaryLinkProcessor implements PageExtension {
+  const GlossaryLinkProcessor();
+
+  @override
+  Future<List<Node>> apply(Page page, List<Node> nodes) async {
+    final glossary = Glossary.fromList(page.data['glossary'] as List<Object?>);
+    return _processNodes(nodes, glossary);
+  }
+
+  List<Node> _processNodes(List<Node> nodes, Glossary glossary) {
+    final processedNodes = <Node>[];
+
+    for (var i = 0; i < nodes.length; i++) {
+      final node = nodes[i];
+
+      if (node is ElementNode &&
+          node.tag == 'a' &&
+          node.attributes['href']?.startsWith('/resources/glossary') == true) {
+        // Found a glossary link, extract its id from the url and
+        // create the tooltip component.
+
+        final id = Uri.parse(node.attributes['href']!).fragment;
+        final entry = glossary.entries.where((e) => e.id == id).firstOrNull;
+
+        if (entry == null) {
+          // If the glossary entry is not found, keep the original node.
+          processedNodes.add(node);
+          continue;
+        }
+
+        processedNodes.add(
+          ElementNode(
+            'span',
+            {'class': 'tooltip-wrapper'},
+            [
+              ElementNode('a', {
+                ...node.attributes,
+                'class': '${node.attributes['class'] ?? ''} tooltip-target'
+                    .trim(),
+              }, node.children),
+              ComponentNode(GlossaryTooltip(entry: entry)),
+            ],
+          ),
+        );
+      } else if (node is ElementNode && node.children != null) {
+        processedNodes.add(
+          ElementNode(
+            node.tag,
+            node.attributes,
+            _processNodes(node.children!, glossary),
+          ),
+        );
+      } else {
+        processedNodes.add(node);
+      }
+    }
+
+    return processedNodes;
+  }
+}
+
+class GlossaryTooltip extends StatelessComponent {
+  const GlossaryTooltip({required this.entry});
+
+  final GlossaryEntry entry;
+
+  @override
+  Component build(BuildContext context) {
+    return span(classes: 'tooltip', [
+      span(classes: 'tooltip-header', [text(entry.term)]),
+      span(classes: 'tooltip-content', [
+        text(entry.shortDescription),
+        text(' '),
+        a(href: '/resources/glossary#${entry.id}', [text('Learn more')]),
+      ]),
+    ]);
+  }
+}

site/lib/src/extensions/registry.dart

@@ -6,6 +6,7 @@ import 'package:jaspr_content/jaspr_content.dart';
 
 import 'attribute_processor.dart';
 import 'code_block_processor.dart';
+import 'glossary_link_processor.dart';
 import 'header_extractor.dart';
 import 'header_processor.dart';
 import 'table_processor.dart';
@@ -18,4 +19,5 @@ const List<PageExtension> allNodeProcessingExtensions = [
   HeaderWrapperExtension(),
   TableWrapperExtension(),
   CodeBlockProcessor(),
+  GlossaryLinkProcessor(),
 ];

site/lib/src/style_hash.dart

@@ -2,4 +2,4 @@
 // dart format off
 
 /// The generated hash of the `main.css` file.
-const generatedStylesHash = 'wjK0Mdh356gO';
+const generatedStylesHash = 'sOkwtE81eV18';