spec-up-t 1.2.8 → 1.3.0-beta

package/assets/css/highlight-heading-plus-sibling-nodes.css

@@ -0,0 +1,6 @@
+.highlight2 {
+    padding-left: 1em;
+    padding-right: 1em;
+    border: 1px dashed #71bbe6;
+    background: #a9dde03b;
+}

package/assets/css/index.css

@@ -3,6 +3,15 @@
   /* Matches sticky header height */
 }
 
+
+/*
+- When a URL fragment targets an element,
+the `:target` pseudo-class triggers the corresponding CSS rules.
+- If the body lacks the hashscroll attribute: 
+   - The targeted element gets highlighted with an animation (highlight-target).
+   - Its parent <dt>(if applicable) gets highlighted with a different animation (highlight-target-parent-dt).
+- These animations visually emphasize the targeted element and its parent for better user experience.
+*/
 body:not([hashscroll]) *:target {
   animation: highlight-target 3.5s 0.25s ease;
 }

package/assets/js/addAnchorsToTerms.js

@@ -1,9 +1,17 @@
 function addAnchorsToTerms() {
-    // Function to find the deepest <span>
-    // Spec-Up is generating nested spans. The deepest span is the main term, and that is what we need.
-    function findDeepestSpan(element) {
+    // Function to find the appropriate span for anchor linking
+    // For external references (tref), we need to use the main term ID, not alias ID
+    function findMainTermSpan(element) {
+        // First, check if this is a transcluded external reference
+        const transcludedSpan = element.querySelector('span.transcluded-xref-term[id^="term:"]');
+        if (transcludedSpan) {
+            // For transcluded external references, always use the main term ID (outermost span)
+            // This ensures that anchor links work correctly with external content insertion
+            return transcludedSpan;
+        }
+        
+        // For regular terms, find the deepest span
         let currentElement = element;
-        // While there is a <span> child, keep going deeper
         while (currentElement.querySelector('span[id^="term:"]')) {
             currentElement = currentElement.querySelector('span[id^="term:"]');
         }
@@ -15,7 +23,7 @@ function addAnchorsToTerms() {
 
     dts.forEach(item => {
 
-        const dt = findDeepestSpan(item);
+        const dt = findMainTermSpan(item);
         const id = dt.getAttribute('id');
         const a = document.createElement('a');
         a.setAttribute('href', `#${id}`);

package/assets/js/collapse-definitions.js

@@ -227,12 +227,6 @@ function collapseDefinitions() {
             button.style.right = `${window.innerWidth - buttonRect.right}px`;
             button.style.zIndex = '1000';
 
-            // Add highlight effect
-            dtElement.classList.add('highlight');
-            setTimeout(() => {
-                dtElement.classList.remove('highlight');
-            }, 0);
-
             // Toggle visibility which might change layout
             toggleVisibility();
 

package/assets/js/fix-last-dd.js

@@ -22,6 +22,9 @@ function fixLastDd() {
         
         // Process each dd element
         ddElements.forEach((dd, index) => {
+            // Remove the 'last-dd' class if it exists, one of the ways it can be there is via the fetching of the external references html. We do not know what classes are in there.
+            dd.classList.remove('last-dd');
+            
             // Get the next sibling element
             let nextSibling = dd.nextElementSibling;
             
@@ -37,8 +40,8 @@ function fixLastDd() {
 }
 
 /**
- * Initializes the function when the DOM content is fully loaded.
+ * Initializes the function when the custom event "trefs-inserted" is fired.
  */
-document.addEventListener("DOMContentLoaded", function () {
-   fixLastDd();
+document.addEventListener("trefs-inserted", function () {
+    fixLastDd();
 });

package/assets/js/highlight-heading-plus-sibling-nodes.js

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Provides functionality to highlight headings and their following sibling nodes
+ * when anchor links are clicked. This module uses event delegation to handle link clicks
+ * and dynamically wraps content sections with highlighting divs.
+ * 
+ * @author Generated by AI Assistant
+ * @version 1.0.0
+ */
+
+/**
+ * Highlights a heading and its following sibling nodes until the next heading of the same level.
+ * Only processes headings h2-h6, excluding h1 elements.
+ * 
+ * @param {string} anchor - The anchor string (e.g., "#linking-to-this-glossary")
+ * @returns {boolean} True if highlighting was successful, false otherwise
+ * 
+ * @example
+ * // Highlight heading with id "section-1" and its content
+ * highlightHeadingSection("#section-1");
+ * 
+ * @example
+ * // Use with anchor from URL hash
+ * highlightHeadingSection(window.location.hash);
+ */
+function highlightHeadingSection(anchor) {
+    // Validate input parameter
+    if (!anchor || typeof anchor !== 'string' || !anchor.startsWith('#')) {
+        console.warn('Invalid anchor provided:', anchor);
+        return false;
+    }
+
+    // Remove existing highlights before adding new ones
+    removeExistingHighlights();
+
+    // Extract the element ID from the anchor
+    const elementId = anchor.substring(1);
+    const targetElement = document.getElementById(elementId);
+
+    if (!targetElement) {
+        console.warn('Element with ID not found:', elementId);
+        return false;
+    }
+
+    // Check if the target element is a valid heading (h2-h6)
+    const headingLevel = getHeadingLevel(targetElement);
+    if (headingLevel === null) {
+        return false;
+    }
+
+    // Find all sibling nodes until the next heading of the same level
+    const nodesToHighlight = collectHeadingSiblings(targetElement, headingLevel);
+
+    // Wrap the collected nodes with highlight div
+    wrapNodesWithHighlight(nodesToHighlight);
+
+    return true;
+}
+
+/**
+ * Determines if an element is a heading and returns its level.
+ * Only considers h2-h6 elements as valid headings.
+ * 
+ * @param {Element} element - The DOM element to check
+ * @returns {number|null} The heading level (2-6) or null if not a valid heading
+ * 
+ * @example
+ * const level = getHeadingLevel(document.querySelector('h3')); // Returns 3
+ * const invalid = getHeadingLevel(document.querySelector('h1')); // Returns null
+ */
+function getHeadingLevel(element) {
+    const tagName = element.tagName.toLowerCase();
+    const headingMatch = tagName.match(/^h([2-6])$/);
+    return headingMatch ? parseInt(headingMatch[1], 10) : null;
+}
+
+/**
+ * Collects a heading element and all its following sibling nodes until the next
+ * heading of the same or higher level in the hierarchy.
+ * 
+ * @param {Element} headingElement - The heading element to start from
+ * @param {number} headingLevel - The level of the heading (2-6)
+ * @returns {Element[]} Array of elements to be highlighted
+ * 
+ * @example
+ * const h3Element = document.querySelector('#my-section');
+ * const siblings = collectHeadingSiblings(h3Element, 3);
+ * // Returns [h3Element, ...following siblings until next h3 or higher]
+ */
+function collectHeadingSiblings(headingElement, headingLevel) {
+    const nodesToHighlight = [headingElement];
+    let currentNode = headingElement.nextElementSibling;
+
+    while (currentNode) {
+        const currentHeadingLevel = getHeadingLevel(currentNode);
+        
+        // Stop if we encounter a heading of the same or higher level
+        if (currentHeadingLevel !== null && currentHeadingLevel <= headingLevel) {
+            break;
+        }
+
+        nodesToHighlight.push(currentNode);
+        currentNode = currentNode.nextElementSibling;
+    }
+
+    return nodesToHighlight;
+}
+
+/**
+ * Wraps a collection of DOM nodes with a highlighting div element.
+ * Creates a div with class "highlight2" and moves all nodes inside it.
+ * 
+ * @param {Element[]} nodes - Array of DOM elements to wrap
+ * @returns {Element|null} The created wrapper div or null if no nodes provided
+ * 
+ * @example
+ * const nodes = [headingEl, paragraphEl, listEl];
+ * const wrapper = wrapNodesWithHighlight(nodes);
+ * // Creates: <div class="highlight2">...nodes...</div>
+ */
+function wrapNodesWithHighlight(nodes) {
+    if (!nodes || nodes.length === 0) {
+        return null;
+    }
+
+    // Create the highlight wrapper div
+    const highlightDiv = document.createElement('div');
+    highlightDiv.className = 'highlight2';
+
+    // Insert the wrapper before the first node
+    const firstNode = nodes[0];
+    firstNode.parentNode.insertBefore(highlightDiv, firstNode);
+
+    // Move all nodes into the wrapper
+    nodes.forEach(node => {
+        highlightDiv.appendChild(node);
+    });
+
+    return highlightDiv;
+}
+
+/**
+ * Removes all existing highlight wrappers from the document.
+ * This ensures only one section is highlighted at a time.
+ * 
+ * @returns {number} The number of highlight divs removed
+ * 
+ * @example
+ * const removedCount = removeExistingHighlights();
+ * console.log(`Removed ${removedCount} existing highlights`);
+ */
+function removeExistingHighlights() {
+    const existingHighlights = document.querySelectorAll('.highlight2');
+    let removedCount = 0;
+
+    existingHighlights.forEach(highlight => {
+        // Move all children back to the parent before removing the wrapper
+        const parent = highlight.parentNode;
+        while (highlight.firstChild) {
+            parent.insertBefore(highlight.firstChild, highlight);
+        }
+        parent.removeChild(highlight);
+        removedCount++;
+    });
+
+    return removedCount;
+}
+
+/**
+ * Handles click events on anchor links and triggers heading highlighting.
+ * Uses event delegation to handle dynamically added links.
+ * 
+ * @param {Event} event - The click event object
+ * @returns {void}
+ * 
+ * @example
+ * // This function is automatically called when anchor links are clicked
+ * // due to the event delegation setup in initializeAnchorHighlighting()
+ */
+function handleAnchorClick(event) {
+    const target = event.target;
+    
+    // Check if the clicked element is a link with an href containing a hash
+    if (target.tagName.toLowerCase() !== 'a') {
+        return;
+    }
+
+    const href = target.getAttribute('href');
+    if (!href || !href.includes('#')) {
+        return;
+    }
+
+    // Extract the anchor part from the href
+    const anchorPart = href.substring(href.indexOf('#'));
+    
+    // Only process if it's an internal anchor (starts with #)
+    if (anchorPart.startsWith('#') && anchorPart.length > 1) {
+        // Small delay to allow browser navigation to complete
+        setTimeout(() => {
+            highlightHeadingSection(anchorPart);
+        }, 100);
+    }
+}
+
+/**
+ * Initializes the anchor link highlighting functionality using event delegation.
+ * Sets up a single click event listener on the document that handles all anchor clicks.
+ * This approach is more efficient than attaching individual listeners to each link.
+ * 
+ * @returns {void}
+ * 
+ * @example
+ * // Initialize the highlighting system
+ * initializeAnchorHighlighting();
+ * 
+ * // Now all anchor links will automatically trigger highlighting
+ * // when clicked, including dynamically added links
+ */
+function initializeAnchorHighlighting() {
+    // Use event delegation to handle all anchor clicks
+    document.addEventListener('click', handleAnchorClick);
+    
+    // Also handle direct navigation to anchors (e.g., page load with hash)
+    if (window.location.hash) {
+        // Delay to ensure DOM is fully loaded
+        setTimeout(() => {
+            highlightHeadingSection(window.location.hash);
+        }, 200);
+    }
+    
+    // Handle browser back/forward navigation
+    window.addEventListener('hashchange', () => {
+        if (window.location.hash) {
+            highlightHeadingSection(window.location.hash);
+        } else {
+            removeExistingHighlights();
+        }
+    });
+}
+
+// Auto-initialize when DOM is ready
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initializeAnchorHighlighting);
+} else {
+    // DOM is already loaded
+    initializeAnchorHighlighting();
+}
+
+// Export functions for potential external use
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        highlightHeadingSection,
+        getHeadingLevel,
+        collectHeadingSiblings,
+        wrapNodesWithHighlight,
+        removeExistingHighlights,
+        initializeAnchorHighlighting
+    };
+}

package/assets/js/insert-trefs.js

@@ -27,11 +27,11 @@ function insertTrefs(allXTrefs) {
        * @type {Array<{element: Element, textContent: string, dt: Element, parent: Element}>}
        */
       const allTerms = [];
-      document.querySelectorAll('dt span.transcluded-xref-term').forEach(termElement => {
-         const textContent = Array.from(termElement.childNodes)
-            .filter(node => node.nodeType === Node.TEXT_NODE)
-            .map(node => node.textContent.trim())
-            .join('');
+
+      document.querySelectorAll('dl.terms-and-definitions-list dt span.transcluded-xref-term').forEach((termElement) => {
+         // Get the full text content including any nested spans (for aliases) of a term (dt)
+         // In case of `[[tref:toip1, agency, ag]]`, this will return `agency`
+         const textContent = termElement.textContent.trim();
 
          // Find the dt element once outside the loop
          const dt = termElement.closest('dt');
@@ -68,7 +68,7 @@ function insertTrefs(allXTrefs) {
 
          // Find the first matching xref to avoid duplicates
          const xref = xtrefsData.xtrefs.find(x => x.term === textContent);
-
+         
          // Create a DocumentFragment to hold all new elements for this term
          const fragment = document.createDocumentFragment();
 
@@ -93,16 +93,22 @@ function insertTrefs(allXTrefs) {
             metaInfoEl.innerHTML = md.render(metaInfo);
             fragment.appendChild(metaInfoEl);
 
-            // Clean up markdown content
+            // Clean up the markdown content in the term definition
+            // Part A: clean up via regex
             let content = xref.content
-               .replace(/\[\[def:[^\]]*?\]\]/g, '') // Remove [[def: ...]] patterns regardless of trailing chars
                .split('\n')
                .map(line => line.replace(/^\s*~\s*/, '')) // Remove leading ~ and spaces
                .join('\n')
-               .replace(/\[\[ref:/g, '') // Remove [[ref: ...]]
                .replace(/\]\]/g, '');
 
-            // Parse the rendered HTML to check for dd elements
+            // Clean up the markdown content in the term definition
+            // Part B: Remove all <a> elements from the content via a temporary div and DOM manipulation
+            const tempDivForLinks = document.createElement('div');
+            tempDivForLinks.innerHTML = md.render(content);
+            tempDivForLinks.querySelectorAll('a').forEach(a => a.replaceWith(...a.childNodes));
+            content = tempDivForLinks.innerHTML;
+
+            // Parse the rendered HTML to check for dd elements. xref.content is a string that contains HTML, in the form of <dd>...</dd>'s
             const tempDiv = document.createElement('div');
             tempDiv.innerHTML = md.render(content);
 
@@ -119,14 +125,17 @@ function insertTrefs(allXTrefs) {
                   fragment.appendChild(clonedDD);
                });
             } else {
-               // No dd elements found, create one to hold the content
+               /*
+                  No dd elements found, create one to hold the conten. Explanation: this is the content in case nothing was found:
+                  `"content": "This term was not found in the external repository"`
+               */
                const contentEl = document.createElement('dd');
                contentEl.classList.add('transcluded-xref-term', 'transcluded-xref-term-embedded');
                contentEl.innerHTML = tempDiv.innerHTML;
                fragment.appendChild(contentEl);
             }
          } else {
-            // Handle case where xref is not found
+            // When the [[tref]] is not valid, for example `[[tref: transferable, transferable]]`, where `transferable` is not an external repo in specs.json
             metaInfoEl.innerHTML = md.render(`
 | Property | Value |
 | -------- | ----- |
@@ -138,7 +147,7 @@ function insertTrefs(allXTrefs) {
 
             // Create not found message
             const notFoundEl = document.createElement('dd');
-            notFoundEl.classList.add('transcluded-xref-term', 'transcluded-xref-term-embedded', 'last-dd');
+
             notFoundEl.innerHTML = '<p>This term was not found in the external repository.</p>';
             fragment.appendChild(notFoundEl);
          }
@@ -160,28 +169,20 @@ function insertTrefs(allXTrefs) {
             const { dt, parent, fragment } = change;
             parent.insertBefore(fragment, dt.nextSibling);
          });
-         
+
          // Dispatch a custom event when all DOM modifications are complete
          // This allows other scripts to know exactly when our work is done
          /**
           * Dispatches a custom event to signal that trefs insertion is complete
           * @fires trefs-inserted
           */
-         document.dispatchEvent(new CustomEvent('trefs-inserted', { 
-            detail: { count: domChanges.length } 
+         document.dispatchEvent(new CustomEvent('trefs-inserted', {
+            detail: { count: domChanges.length }
          }));
       });
    }
 
-   if (allXTrefs?.xtrefs) {
-      processTerms(allXTrefs);
-   } else {
-      console.error('allXTrefs is undefined or missing xtrefs property');
-      // Dispatch event even when there are no xrefs, so waiting code knows we're done
-      document.dispatchEvent(new CustomEvent('trefs-inserted', { 
-         detail: { count: 0, error: 'Missing xtrefs data' } 
-      }));
-   }
+   processTerms(allXTrefs);
 }
 
 /**
@@ -231,11 +232,14 @@ function initializeOnTrefsInserted(initCallback) {
  * @listens DOMContentLoaded
  */
 document.addEventListener('DOMContentLoaded', () => {
-   // Check if allXTrefs is defined in the global scope
-   if (typeof allXTrefs !== 'undefined') {
+   if (typeof allXTrefs !== 'undefined' && allXTrefs?.xtrefs) {
       insertTrefs(allXTrefs);
    } else {
-      console.warn('allXTrefs is not available in the global scope. Transcluded references will not be inserted.');
+      console.error('allXTrefs is undefined or missing xtrefs property');
+      // Dispatch event even when there are no xrefs, so waiting code knows we're done
+      document.dispatchEvent(new CustomEvent('trefs-inserted', {
+         detail: { count: 0, error: 'Missing xtrefs data' }
+      }));
    }
 });
 

package/config/asset-map.json

@@ -26,6 +26,7 @@
       "assets/css/image-full-size.css",
       "assets/css/add-bootstrap-classes-to-images.css",
       "assets/css/horizontal-scroll-hint.css",
+      "assets/css/highlight-heading-plus-sibling-nodes.css",
       "assets/css/index.css"
     ],
     "js": [
@@ -72,6 +73,7 @@
       "assets/js/horizontal-scroll-hint.js",
       "assets/js/add-bootstrap-classes-to-images.js",
       "assets/js/image-full-size.js",
+      "assets/js/highlight-heading-plus-sibling-nodes.js",
       "assets/js/bootstrap.bundle.min.js"
     ]
   }

package/gulpfile.js

@@ -19,9 +19,15 @@ async function fetchSpecRefs() {
   return Promise.all([
     axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/ietf.json'),
     axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/w3c.json'),
-    axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/whatwg.json')
+    axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/whatwg.json'),
+    axios.get('https://raw.githubusercontent.com/tobie/specref/master/refs/biblio.json')
   ]).then(async results => {
-    let json = Object.assign(results[0].data, results[1].data, results[2].data);
+    let json = Object.assign(
+      results[0].data,// IETF
+      results[1].data,// W3C
+      results[2].data,// WHATWG
+      results[3].data// Biblio
+    );
     return fs.outputFile(compileLocation + '/refs.json', JSON.stringify(json));
   }).catch(e => console.log(e));
 }