spec-up-t 1.3.1 → 1.4.0

package/assets/js/terminology-section-utility-container/search.js

@@ -0,0 +1,203 @@
+/**
+ * @file Search functionality for terminology section
+ * @author Kor Dwarshuis
+ * @version 1.0.0
+ * @since 2024-08-31
+ * @description Handles search logic and highlighting (DOM is constructed in main module)
+ */
+
+/**
+ * Attaches search functionality to the provided DOM elements
+ * @param {HTMLInputElement} searchInput - The search input element
+ * @param {HTMLButtonElement} goToPreviousMatchButton - Previous match button
+ * @param {HTMLButtonElement} goToNextMatchButton - Next match button
+ * @param {HTMLSpanElement} totalMatchesSpan - Matches counter element
+ * @returns {void}
+ */
+function attachSearchFunctionality(searchInput, goToPreviousMatchButton, goToNextMatchButton, totalMatchesSpan) {
+    // Check if the terms and definitions list exists
+    const termsListElement = document.querySelector(".terms-and-definitions-list");
+    const dtElements = termsListElement ? termsListElement.querySelectorAll("dt") : [];
+
+    if (dtElements.length === 0) {
+        return;
+    }
+
+    /*****************/
+    /* CONFIGURATION */
+    const matchesStyle = specConfig.searchHighlightStyle || 'ssi';
+    const debounceTime = 600;
+    const matches = 'matches';
+    const searchableContent = document.querySelector('.terms-and-definitions-list');
+
+    // Styling of search matches
+    const matchesStyleSelector = {
+        dif: 'highlight-matches-DIF-search',
+        toip: 'highlight-matches-ToIP-search',
+        btc: 'highlight-matches-BTC-search',
+        keri: 'highlight-matches-KERI-search',
+        ssi: 'highlight-matches-SSI-search',
+        gleif: 'highlight-matches-GLEIF-search'
+    };
+
+    const matchesClassName = "highlight-matches-search";
+    const matchesStyleSelectorClassName = matchesStyleSelector[matchesStyle.toLowerCase()];
+    
+    let totalMatches = 0;
+    let activeMatchIndex = -1;
+    let debounceTimeout;
+
+    /* Helper functions */
+    function setTotalMatches() {
+        totalMatches = document.querySelectorAll('.' + matchesClassName).length;
+        totalMatchesSpan.innerHTML = `${totalMatches} ${matches}`;
+    }
+
+    function handleBackAndForthButtonsDisabledState() {
+        const hasMatches = totalMatches > 0;
+        goToPreviousMatchButton.disabled = !hasMatches;
+        goToNextMatchButton.disabled = !hasMatches;
+    }
+
+    function scrollToElementCenter(element) {
+        if (element) {
+            element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        }
+    }
+
+    function removeHighlights() {
+        const highlighted = document.querySelectorAll('.' + matchesClassName);
+        highlighted.forEach(element => {
+            const parent = element.parentNode;
+            parent.replaceChild(document.createTextNode(element.textContent), element);
+            parent.normalize();
+        });
+    }
+
+    function highlightMatches(query) {
+        if (!query.trim()) {
+            removeHighlights();
+            setTotalMatches();
+            handleBackAndForthButtonsDisabledState();
+            return;
+        }
+
+        removeHighlights();
+        
+        const regex = new RegExp(`(${query.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')})`, 'gi');
+        
+        function searchNodes(node) {
+            if (node.nodeType === 3) { // Text node
+                const text = node.textContent;
+                if (regex.test(text)) {
+                    const fragments = document.createDocumentFragment();
+                    let lastIndex = 0;
+                    let match;
+                    
+                    regex.lastIndex = 0; // Reset regex
+                    while ((match = regex.exec(text)) !== null) {
+                        // Add text before match
+                        if (match.index > lastIndex) {
+                            fragments.appendChild(document.createTextNode(text.slice(lastIndex, match.index)));
+                        }
+                        
+                        // Add highlighted match
+                        const span = document.createElement('span');
+                        span.className = `${matchesClassName} ${matchesStyleSelectorClassName}`;
+                        span.textContent = match[0];
+                        fragments.appendChild(span);
+                        
+                        lastIndex = regex.lastIndex;
+                    }
+                    
+                    // Add remaining text
+                    if (lastIndex < text.length) {
+                        fragments.appendChild(document.createTextNode(text.slice(lastIndex)));
+                    }
+                    
+                    node.parentNode.replaceChild(fragments, node);
+                }
+            } else if (node.nodeType === 1) { // Element node
+                Array.from(node.childNodes).forEach(searchNodes);
+            }
+        }
+
+        searchNodes(searchableContent);
+        setTotalMatches();
+        handleBackAndForthButtonsDisabledState();
+        activeMatchIndex = -1;
+        
+        // Scroll to first match
+        const firstHighlight = document.querySelector('.' + matchesClassName);
+        if (firstHighlight) {
+            scrollToElementCenter(firstHighlight);
+        }
+    }
+
+    function debouncedSearchAndHighlight(query, shouldScrollToFirstMatch = false) {
+        clearTimeout(debounceTimeout);
+        debounceTimeout = setTimeout(() => {
+            highlightMatches(query);
+        }, debounceTime);
+    }
+
+    function navigateMatches(direction) {
+        const allMatches = document.querySelectorAll('.' + matchesClassName);
+        if (allMatches.length === 0) return;
+
+        if (direction === 'next') {
+            activeMatchIndex = (activeMatchIndex + 1) % allMatches.length;
+        } else {
+            activeMatchIndex = activeMatchIndex <= 0 ? allMatches.length - 1 : activeMatchIndex - 1;
+        }
+
+        // Remove previous active styling
+        allMatches.forEach(match => match.classList.remove('active'));
+        
+        // Add active styling and scroll to current match
+        allMatches[activeMatchIndex].classList.add('active');
+        scrollToElementCenter(allMatches[activeMatchIndex]);
+    }
+
+    /* Event listeners */
+    searchInput.addEventListener("input", function () {
+        debouncedSearchAndHighlight(searchInput.value, true);
+    });
+
+    goToNextMatchButton.addEventListener('click', () => navigateMatches('next'));
+    goToPreviousMatchButton.addEventListener('click', () => navigateMatches('prev'));
+
+    // Global keyboard navigation (Arrow keys work anywhere on the page)
+    document.addEventListener('keyup', (event) => {
+        if (totalMatches > 0) {
+            switch (event.key) {
+                case "ArrowRight":
+                    goToNextMatchButton.click(); // Simulate a click on button
+                    break;
+                case "ArrowLeft":
+                    goToPreviousMatchButton.click(); // Simulate a click on button
+                    break;
+            }
+        }
+    });
+
+    // Keyboard navigation when search input is focused
+    document.addEventListener('keydown', function(event) {
+        if (document.activeElement === searchInput) {
+            if (event.key === 'ArrowDown' && totalMatches > 0) {
+                event.preventDefault();
+                navigateMatches('next');
+            } else if (event.key === 'ArrowUp' && totalMatches > 0) {
+                event.preventDefault();
+                navigateMatches('prev');
+            }
+        }
+    });
+
+    // Re-run search when definitions are collapsed/expanded
+    document.addEventListener('click', event => {
+        if (event.target.classList.contains('collapse-all-defs-button')) {
+            debouncedSearchAndHighlight(searchInput.value, true);
+        }
+    });
+}

package/assets/js/terminology-section-utility-container.js

@@ -0,0 +1,203 @@
+/**
+ * @file Main module for terminology section utility container functionality
+ * @author Kor Dwarshuis
+ * @version 1.0.0
+ * @since 2024-08-31
+ * @description Coordinates all terminology section utility container components
+ */
+
+/**
+ * Initializes the complete terminology section utility container
+ * This function coordinates all the components in the correct order
+ */
+function initializeTerminologyUtilityContainer() {
+    // Check if the terms and definitions list exists
+    const termsListElement = document.querySelector(".terms-and-definitions-list");
+    const dtElements = termsListElement ? termsListElement.querySelectorAll("dt") : [];
+
+    if (dtElements.length === 0) {
+        // Hide the container if no terms exist
+        hideShowUtilityContainer();
+        return;
+    }
+
+    const terminologySectionUtilityContainer = document.getElementById("terminology-section-utility-container");
+    
+    // Build alphabet index data
+    const alphabetIndex = {};
+    dtElements.forEach(dt => {
+        const span = dt.querySelector("span");
+        if (span?.id) {
+            const termId = span.id;
+            const firstChar = termId.charAt(termId.indexOf("term:") + 5).toUpperCase();
+            if (!alphabetIndex[firstChar]) {
+                alphabetIndex[firstChar] = span.id;
+            }
+        }
+    });
+
+    /*************************************************/
+    /* DOM CONSTRUCTION - COMPLETE LAYOUT STRUCTURE */
+    /*************************************************/
+
+    /* ===== ROW 1: ALPHABET INDEX ===== */
+    // ALPHABET INDEX TEMPORARILY DISABLED
+    // const alphabetRow = document.createElement("div");
+    // alphabetRow.className = "row mb-2";
+    // 
+    // const alphabetCol = document.createElement("div");
+    // alphabetCol.className = "col-12";
+    // 
+    // const alphabetIndexContainer = document.createElement("div");
+    // alphabetIndexContainer.className = "d-flex flex-wrap justify-content-center gap-2";
+
+    // // Create alphabet links
+    // Object.keys(alphabetIndex).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())).forEach(char => {
+    //     const link = document.createElement("a");
+    //     link.href = `#${alphabetIndex[char]}`;
+    //     link.textContent = char;
+    //     link.className = "btn btn-outline-secondary btn-sm";
+    //     alphabetIndexContainer.appendChild(link);
+    // });
+
+    // alphabetCol.appendChild(alphabetIndexContainer);
+    // alphabetRow.appendChild(alphabetCol);
+
+    /* ===== ROW 2: UTILITIES (TERM COUNT + FILTERS + SEARCH) ===== */
+    const utilityRow = document.createElement("div");
+    utilityRow.className = "row g-2";
+    utilityRow.id = "utility-row";
+    
+    // Left column: Term count
+    const leftCol = document.createElement("div");
+    leftCol.className = "col-auto d-flex align-items-center";
+
+    // Term count
+    const numberOfTerms = document.createElement("small");
+    numberOfTerms.className = "text-muted mb-0";
+    numberOfTerms.textContent = `${dtElements.length} terms`;
+    leftCol.appendChild(numberOfTerms);
+
+    // Center column: Filters and Versions button
+    const centerCol = document.createElement("div");
+    centerCol.className = "col d-flex flex-wrap align-items-center gap-3";
+
+    // Filter checkboxes container
+    const checkboxesContainer = document.createElement('div');
+    checkboxesContainer.className = 'd-flex gap-3';
+    
+    // Local terms checkbox
+    const localTermsCheckboxDiv = document.createElement('div');
+    localTermsCheckboxDiv.className = 'form-check';
+    localTermsCheckboxDiv.innerHTML = `
+        <input class="form-check-input" type="checkbox" id="showLocalTermsCheckbox" checked>
+        <label class="form-check-label" for="showLocalTermsCheckbox">
+            Local
+        </label>
+    `;
+    
+    // External terms checkbox
+    const externalTermsCheckboxDiv = document.createElement('div');
+    externalTermsCheckboxDiv.className = 'form-check';
+    externalTermsCheckboxDiv.innerHTML = `
+        <input class="form-check-input" type="checkbox" id="showExternalTermsCheckbox" checked>
+        <label class="form-check-label" for="showExternalTermsCheckbox">
+            Remote
+        </label>
+    `;
+    
+    checkboxesContainer.appendChild(localTermsCheckboxDiv);
+    checkboxesContainer.appendChild(externalTermsCheckboxDiv);
+    centerCol.appendChild(checkboxesContainer);
+
+    // Snapshot link
+    const snapshotLink = document.createElement('a');
+    snapshotLink.id = 'snapshot-link-in-content';
+    snapshotLink.className = 'btn btn-outline-primary btn-sm';
+    // snapshotLink.href = './versions/';
+    snapshotLink.href = '#';
+    snapshotLink.textContent = 'Versions';
+    centerCol.appendChild(snapshotLink);
+
+    // Right column: Search
+    const rightCol = document.createElement("div");
+    rightCol.className = "col-auto d-flex justify-content-end";
+
+    // Search container
+    const searchContainer = document.createElement("div");
+    searchContainer.setAttribute("id", "container-search");
+    searchContainer.classList.add("input-group", "input-group-sm");
+    searchContainer.setAttribute("role", "search");
+
+    // Search input
+    const searchInput = document.createElement("input");
+    searchInput.setAttribute("type", "text");
+    searchInput.setAttribute("id", "search");
+    searchInput.classList.add("form-control");
+    searchInput.setAttribute("placeholder", "🔍 (terms only)");
+    searchInput.setAttribute("aria-label", "Search terms");
+    searchInput.setAttribute("autocomplete", "off");
+    searchContainer.appendChild(searchInput);
+
+    // Search button group
+    const buttonGroup = document.createElement("div");
+    buttonGroup.classList.add("input-group-text", "p-0");
+
+    // Previous match button
+    const goToPreviousMatchButton = document.createElement("button");
+    goToPreviousMatchButton.setAttribute("id", "one-match-backward-search");
+    goToPreviousMatchButton.classList.add("btn", "btn-outline-secondary");
+    goToPreviousMatchButton.setAttribute("type", "button");
+    goToPreviousMatchButton.setAttribute("disabled", "true");
+    goToPreviousMatchButton.setAttribute("title", "Go to previous match (Left Arrow)");
+    goToPreviousMatchButton.setAttribute("aria-label", "Go to previous match");
+    goToPreviousMatchButton.innerHTML = '<span aria-hidden="true">▲</span>';
+    buttonGroup.appendChild(goToPreviousMatchButton);
+
+    // Next match button
+    const goToNextMatchButton = document.createElement("button");
+    goToNextMatchButton.setAttribute("id", "one-match-forward-search");
+    goToNextMatchButton.classList.add("btn", "btn-outline-secondary");
+    goToNextMatchButton.setAttribute("type", "button");
+    goToNextMatchButton.setAttribute("disabled", "true");
+    goToNextMatchButton.setAttribute("title", "Go to next match (Right Arrow)");
+    goToNextMatchButton.setAttribute("aria-label", "Go to next match");
+    goToNextMatchButton.innerHTML = '<span aria-hidden="true">▼</span>';
+    buttonGroup.appendChild(goToNextMatchButton);
+
+    // Matches counter
+    const totalMatchesSpan = document.createElement("span");
+    totalMatchesSpan.setAttribute("id", "total-matches-search");
+    totalMatchesSpan.classList.add("input-group-text");
+    totalMatchesSpan.innerHTML = "0 matches";
+    totalMatchesSpan.setAttribute("aria-live", "polite");
+    totalMatchesSpan.setAttribute("role", "status");
+    searchContainer.appendChild(totalMatchesSpan);
+
+    searchContainer.appendChild(buttonGroup);
+    rightCol.appendChild(searchContainer);
+
+    utilityRow.appendChild(leftCol);
+    utilityRow.appendChild(centerCol);
+    utilityRow.appendChild(rightCol);
+
+    /* ===== ASSEMBLE COMPLETE STRUCTURE ===== */
+    // ALPHABET INDEX TEMPORARILY DISABLED
+    // terminologySectionUtilityContainer.appendChild(alphabetRow);
+    terminologySectionUtilityContainer.appendChild(utilityRow);
+
+    /*****************************************/
+    /* INITIALIZE FUNCTIONALITY COMPONENTS  */
+    /*****************************************/
+
+    // Initialize functionalities (these will attach to the DOM elements we just created)
+    // ALPHABET INDEX TEMPORARILY DISABLED
+    // attachAlphabetIndexFunctionality();
+    attachTermFilterFunctionality(checkboxesContainer);
+    attachSearchFunctionality(searchInput, goToPreviousMatchButton, goToNextMatchButton, totalMatchesSpan);
+}
+
+// Initialize when DOM is ready
+document.addEventListener("DOMContentLoaded", function () {
+    initializeTerminologyUtilityContainer();
+});

package/assets/js/tooltips.js

@@ -0,0 +1,283 @@
+(function () {
+  'use strict';
+
+  /**
+   * TOOLTIP SYSTEM OVERVIEW
+   * =======================
+   * This module creates interactive tooltips for term references in the specification.
+   * It handles two types of content sources:
+   * 
+   * 1. LOCAL TERMS (tref and def): Content from the current document's DOM
+   *    - These are definition lists <dt>/<dd> or table rows <tr>/<td>
+   *    - Example: [[def: term, alias]] creates a local definition
+   *    - Example: [[tref: ., term, alias]] references a local term
+   * 
+   * 2. EXTERNAL TERMS (xref): Content from external specifications
+   *    - These come from the global allXTrefs data structure
+   *    - Example: [[tref: externalreference, term]] references an external term
+   *    - The allXTrefs data is populated by src/pipeline/references/external-references-service.js during build time
+   *    - External content is fetched from other GitHub-hosted specifications
+   */
+
+  /* Tooltips WeakMap storage for performance optimization */
+  // WeakMap prevents memory leaks by automatically garbage collecting 
+  // when DOM elements are removed
+  let tipMap = new WeakMap();
+
+  /**
+   * EVENT DELEGATION FOR TOOLTIP TRIGGERS
+   * =====================================
+   * Uses delegateEvent (from utils.js) to efficiently handle hover events.
+   * Event delegation attaches a single listener to the document rather than
+   * individual listeners on each term reference, improving performance.
+   * 
+   * TARGET SELECTORS:
+   * - '.term-reference': Generated for [[tref: ...]] and [[def: ...]] constructions
+   * - '.spec-reference': Generated for specification references
+   * 
+   * TRIGGER EVENT: 'pointerover' 
+   * - Fires when mouse enters the element (more reliable than 'mouseenter')
+   * - Works on both mouse and touch devices
+   */
+  delegateEvent('pointerover', '.term-reference, .spec-reference', (e, anchor) => {
+    /**
+     * EXTRACT TARGET INFORMATION
+     * =========================
+     * The anchor element contains attributes that tell us what term to show:
+     * 
+     * - data-local-href: For local references (format: #termname or #term:external:termname)
+     * - href: Fallback attribute for standard links
+     * 
+     * Examples of generated markup:
+     * - [[def: myterm]] creates: <a class="term-reference" data-local-href="#myterm">myterm</a>
+     * - [[tref: ., myterm]] creates: <a class="term-reference" data-local-href="#myterm">myterm</a>
+     * - [[tref: external, myterm]] creates: <a class="term-reference" data-local-href="#term:external:myterm">myterm</a>
+     */
+    const id = anchor.getAttribute('data-local-href') || anchor.getAttribute('href') || '';
+    
+    /**
+     * ATTEMPT TO FIND LOCAL DOM ELEMENT
+     * ================================
+     * Try to find a DOM element with the ID (removing the # prefix).
+     * This works for local definitions and some tref references.
+     */
+    let term = document.getElementById(id.replace('#', ''));
+
+    /**
+     * TOOLTIP CONFIGURATION
+     * ====================
+     * Base configuration for Tippy.js tooltips:
+     * - allowHTML: Enables rich HTML content in tooltips
+     * - inlinePositioning: Positions tooltip relative to cursor for better UX
+     */
+    let tip = {
+      allowHTML: true,
+      inlinePositioning: true
+    };
+
+    /**
+     * PREVENT DUPLICATE TOOLTIPS
+     * =========================
+     * Check if we've already created a tooltip for this anchor element.
+     * The WeakMap ensures efficient lookup and automatic cleanup.
+     */
+    if (tipMap.has(anchor)) return;
+
+    if (term) {
+      /**
+       * LOCAL DOM-BASED TOOLTIP CONTENT
+       * ===============================
+       * When we find a matching DOM element, extract content from it.
+       * The spec-up system creates definitions in two main formats:
+       * 
+       * 1. DEFINITION LIST FORMAT:
+       *    <dt id="myterm">Term Name</dt>
+       *    <dd>Term definition content goes here</dd>
+       * 
+       * 2. TABLE FORMAT:
+       *    <table>
+       *      <thead><tr><th>Term</th><th>Definition</th><th>Source</th></tr></thead>
+       *      <tbody><tr><td id="myterm">Term Name</td><td>Definition</td><td>Source</td></tr></tbody>
+       *    </table>
+       */
+      
+      // Find the container element that holds the term definition
+      // Look for either <dt> (definition term) or first <td> (table cell)
+      let container = term.closest('dt, td:first-child');
+      if (!container) return;
+
+      switch (container.tagName) {
+        case 'DT':
+          /**
+           * DEFINITION LIST PROCESSING
+           * =========================
+           * In a definition list, the <dt> contains the term name,
+           * and the next sibling <dd> contains the definition text.
+           * We extract the text content from the <dd> element.
+           * If the first <dd> has class 'meta-info-content-wrapper', skip it and use the next <dd>.
+           */
+          let dd = container.nextElementSibling;
+          if (dd && dd.tagName === 'DD' && dd.classList.contains('meta-info-content-wrapper')) {
+            dd = dd.nextElementSibling;
+          }
+          if (dd && dd.tagName === 'DD') {
+            tip.content = dd.textContent;
+          }
+          break;
+          
+        case 'TD':
+          /**
+           * TABLE FORMAT PROCESSING
+           * ======================
+           * For table-based definitions, we create a mini table showing
+           * all the metadata associated with the term. This provides
+           * richer context than just the definition text.
+           * 
+           * Process:
+           * 1. Find the parent table and get all header cells
+           * 2. Get all data cells from the current row
+           * 3. Create HTML table mapping headers to values
+           * 4. Skip the first column (which contains the term name itself)
+           */
+          let table = container.closest('table');
+          let tds = Array.from(container.closest('tr').children);
+          tds.shift(); // Remove first cell (the term name)
+          
+          if (table) {
+            let headings = Array.from(table.querySelectorAll('thead th'));
+            headings.shift(); // Remove first heading (matches the term name column)
+            
+            if (headings.length) {
+              tip.content = `
+              <header>${container.textContent}</header>
+              <table>
+                ${headings.map((th, i) => {
+                return `<tr><td>${th.textContent}:</td><td>${tds[i] ? tds[i].textContent : ''}</td></tr>`
+              }).join('')}
+              </table>`;
+            }
+          }
+          break;
+      }
+    } else {
+      /**
+       * EXTERNAL REFERENCE TOOLTIP CONTENT
+       * ==================================
+       * When no local DOM element is found, this is likely an external reference (xref).
+       * External references have the format: #term:externalSpec:termName
+       * 
+       * THE allXTrefs DATA SOURCE:
+       * -------------------------
+       * The allXTrefs global variable is created during the build process by:
+   * 1. src/pipeline/references/external-references-service.js - Orchestrates external reference collection
+  * 2. src/pipeline/references/ - Fetches content from external GitHub specs
+       * 3. The data is written to a JavaScript file and included in the page
+       * 
+       * DATA STRUCTURE:
+       * allXTrefs = {
+       *   xtrefs: [
+       *     {
+       *       externalSpec: "spec-name",     // The external specification identifier
+       *       term: "term-name",             // The term being referenced
+       *       content: "Definition text...",  // The definition content from external spec
+       *       url: "https://...",            // Source URL
+       *       // ... other metadata
+       *     }
+       *   ]
+       * }
+       * 
+       * EXTERNAL SPEC FETCHING PROCESS:
+       * ------------------------------
+       * 1. External specs are defined in specs-configuration.yml
+       * 2. During build, the system fetches HTML from external GitHub Pages
+       * 3. Term definitions are extracted from the external HTML
+       * 4. Content is cached in JSON and JS files for runtime use
+       * 5. This allows tooltips to show definitions from other specifications
+       */
+      
+      // Handle xref terms from allXTrefs data (when no DOM element found)
+      const href = anchor.getAttribute('data-local-href') || '';
+      
+      /**
+       * PARSE EXTERNAL REFERENCE FORMAT
+       * ===============================
+       * Expected format: #term:externalSpec:termName
+       * Example: #term:KERI:delegator means:
+       * - externalSpec: "KERI" 
+       * - termName: "delegator"
+       */
+      const match = href.match(/#term:([^:]+):(.+)/);
+      if (match) {
+        const [, externalSpec, termName] = match;
+
+        /**
+         * LOOKUP IN EXTERNAL REFERENCES DATA
+         * =================================
+         * Search the global allXTrefs data for matching term.
+         * Uses case-insensitive matching to handle inconsistencies
+         * between how terms are defined vs. referenced.
+         */
+        if (typeof allXTrefs !== 'undefined' && allXTrefs.xtrefs && allXTrefs.xtrefs.length > 0) {
+          // Look for term with case-insensitive matching to handle case inconsistencies
+          const foundTerm = allXTrefs.xtrefs.find(xtref =>
+            xtref.externalSpec === externalSpec &&
+            xtref.term.toLowerCase() === termName.toLowerCase()
+          );
+
+          if (foundTerm && foundTerm.content) {
+            /**
+             * CLEAN HTML CONTENT FOR TOOLTIP
+             * ==============================
+             * The external content may contain HTML markup that's not suitable
+             * for tooltips. We create a temporary DOM element to extract
+             * clean text content while preserving structure.
+             */
+            // Strip HTML tags for clean text tooltip
+            const tempDiv = document.createElement('div');
+            tempDiv.innerHTML = foundTerm.content;
+            tip.content = tempDiv.textContent || tempDiv.innerText || '';
+          }
+        }
+      }
+    }
+
+    /**
+     * CREATE AND STORE TOOLTIP
+     * ========================
+     * If we successfully extracted content (from either local DOM or external data),
+     * create the actual tooltip using Tippy.js library and store it in our WeakMap
+     * for future reference and duplicate prevention.
+     * 
+     * TIPPY.JS INTEGRATION:
+     * - tippy() creates the interactive tooltip element
+     * - WeakMap storage prevents memory leaks and duplicate creation
+     * - Tooltip appears on hover and includes rich formatting
+     */
+    if (tip.content) {
+      tipMap.set(anchor, tippy(anchor, tip))
+    };
+  }, { passive: true }); // passive: true improves scroll performance
+
+  /**
+   * MODULE SUMMARY
+   * =============
+   * This tooltip system provides contextual help for specification terms by:
+   * 
+   * 1. LISTENING: Uses event delegation to efficiently handle hover events
+   * 2. IDENTIFYING: Determines if term is local (DOM-based) or external (xref)
+   * 3. EXTRACTING: Gets content from appropriate source (DOM elements or allXTrefs data)
+   * 4. DISPLAYING: Creates rich tooltips with Tippy.js
+   * 5. CACHING: Prevents duplicate tooltip creation with WeakMap storage
+   * 
+   * CONTENT SOURCES:
+   * - Local definitions: From <dt>/<dd> or table rows in current document
+   * - External references: From allXTrefs global data (fetched during build)
+   * 
+   * MARKDOWN SYNTAX SUPPORTED:
+   * - [[def: term, alias]] - Creates local definition
+   * - [[tref: ., term, alias]] - References local term  
+   * - [[tref: externalreference, term]] - References external term
+   * - [[xref: externalreference, term]] - External reference (alias for tref)
+   */
+
+})();