spec-up-t 1.3.0 → 1.4.0

package/assets/js/github-repo-info.js

@@ -0,0 +1,144 @@
+/**
+ * GitHub Repository Information Utility
+ * 
+ * This client-side utility provides easy access to the GitHub repository
+ * information embedded in the HTML meta tag by Spec-Up-T.
+ * 
+ * Usage:
+ *   const repoInfo = getGithubRepoInfo();
+ *   if (repoInfo) {
+ *     console.log(`Repository: ${repoInfo.username}/${repoInfo.repo} on ${repoInfo.branch}`);
+ *   }
+ */
+
+/**
+ * Extracts GitHub repository information from the meta tag
+ * @returns {Object|null} Repository information object or null if not found
+ * @returns {string} returns.username - GitHub username/account
+ * @returns {string} returns.repo - Repository name
+ * @returns {string} returns.branch - Git branch name
+ */
+function getGithubRepoInfo() {
+    try {
+        const metaTag = document.querySelector('meta[property="spec-up-t:github-repo-info"]');
+        if (!metaTag) {
+            console.warn('GitHub repository meta tag not found');
+            return null;
+        }
+        
+        const content = metaTag.getAttribute('content');
+        if (!content) {
+            console.warn('GitHub repository meta tag has no content');
+            return null;
+        }
+        
+        const [username, repo, branch] = content.split(',');
+        if (!username || !repo || !branch) {
+            console.warn('Invalid GitHub repository meta tag format');
+            return null;
+        }
+        
+        return {
+            username: username.trim(),
+            repo: repo.trim(),
+            branch: branch.trim()
+        };
+    } catch (error) {
+        console.error('Error extracting GitHub repository information:', error);
+        return null;
+    }
+}
+
+/**
+ * Creates a GitHub URL from the repository information
+ * @param {string} path - Optional path within the repository (e.g., 'issues', 'blob/main/README.md')
+ * @returns {string|null} GitHub URL or null if repository info not available
+ */
+function getGithubUrl(path = '') {
+    const repoInfo = getGithubRepoInfo();
+    if (!repoInfo) {
+        return null;
+    }
+    
+    const baseUrl = `https://github.com/${repoInfo.username}/${repoInfo.repo}`;
+    if (path) {
+        return `${baseUrl}/${path}`;
+    }
+    return baseUrl;
+}
+
+/**
+ * Gets the GitHub URL for the current branch
+ * @returns {string|null} GitHub branch URL or null if repository info not available
+ */
+function getCurrentBranchUrl() {
+    const repoInfo = getGithubRepoInfo();
+    if (!repoInfo) {
+        return null;
+    }
+    
+    return `https://github.com/${repoInfo.username}/${repoInfo.repo}/tree/${repoInfo.branch}`;
+}
+
+/**
+ * Populates the repository information in the settings menu
+ * This function is called when the page loads to display repo info
+ */
+function populateRepoInfoInSettings() {
+    const repoInfo = getGithubRepoInfo();
+    
+    // Get DOM elements for repository info display
+    const accountElement = document.getElementById('repo-account');
+    const nameElement = document.getElementById('repo-name');
+    const branchElement = document.getElementById('repo-branch');
+    const urlElement = document.getElementById('repo-url');
+    
+    if (!accountElement || !nameElement || !branchElement || !urlElement) {
+        console.warn('Repository info elements not found in settings menu');
+        return;
+    }
+    
+    if (repoInfo) {
+        // Populate the information
+        accountElement.textContent = repoInfo.username;
+        nameElement.textContent = repoInfo.repo;
+        branchElement.textContent = repoInfo.branch;
+        
+        // Set up the GitHub link
+        const repoUrl = getGithubUrl();
+        if (repoUrl) {
+            urlElement.href = repoUrl;
+            urlElement.style.display = 'inline-block';
+        } else {
+            urlElement.style.display = 'none';
+        }
+    } else {
+        // Handle case where no repository info is available
+        accountElement.textContent = 'Not available';
+        nameElement.textContent = 'Not available';
+        branchElement.textContent = 'Not available';
+        urlElement.style.display = 'none';
+    }
+}
+
+// Initialize repository info when DOM is ready
+document.addEventListener('DOMContentLoaded', function() {
+    populateRepoInfoInSettings();
+});
+
+// Make functions available globally if not using modules
+if (typeof window !== 'undefined') {
+    window.getGithubRepoInfo = getGithubRepoInfo;
+    window.getGithubUrl = getGithubUrl;
+    window.getCurrentBranchUrl = getCurrentBranchUrl;
+    window.populateRepoInfoInSettings = populateRepoInfoInSettings;
+}
+
+// Export for module usage
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        getGithubRepoInfo,
+        getGithubUrl,
+        getCurrentBranchUrl
+    };
+}

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

@@ -14,6 +14,7 @@ const {
   initializeAnchorHighlighting
 } = require('./highlight-heading-plus-sibling-nodes');
 
+// Tests for highlighting heading sections and their related content
 describe('highlight-heading-plus-sibling-nodes', () => {
   let container;
 
@@ -36,11 +37,14 @@ describe('highlight-heading-plus-sibling-nodes', () => {
     document.body.innerHTML = '';
   });
 
+  // Tests for determining heading levels (h2-h6)
   describe('getHeadingLevel', () => {
+    // Test: Can the system correctly identify heading levels?
     it('returns correct level for h2-h6', () => {
       expect(getHeadingLevel(document.getElementById('h2-1'))).toBe(2);
       expect(getHeadingLevel(document.getElementById('h3-1'))).toBe(3);
     });
+    // Test: Does the system properly reject invalid headings?
     it('returns null for h1 or non-heading', () => {
       const h1 = document.createElement('h1');
       expect(getHeadingLevel(h1)).toBeNull();
@@ -48,12 +52,15 @@ describe('highlight-heading-plus-sibling-nodes', () => {
     });
   });
 
+  // Tests for collecting heading sections (heading + related content)
   describe('collectHeadingSiblings', () => {
+    // Test: Can the system collect all content belonging to a heading section?
     it('collects heading and following siblings until next heading of same or higher level', () => {
       const h2 = document.getElementById('h2-1');
       const siblings = collectHeadingSiblings(h2, 2);
       expect(siblings.map(n => n.id)).toEqual(['h2-1', 'p1', 'ul1', 'h3-1', 'p2']);
     });
+    // Test: Does the system stop collecting at the right boundary?
     it('stops at next heading of same or higher level', () => {
       const h3 = document.getElementById('h3-1');
       const siblings = collectHeadingSiblings(h3, 3);
@@ -61,7 +68,9 @@ describe('highlight-heading-plus-sibling-nodes', () => {
     });
   });
 
+  // Tests for wrapping content with highlight styling
   describe('wrapNodesWithHighlight', () => {
+    // Test: Can the system wrap selected content with highlight styling?
     it('wraps nodes in a div.highlight2', () => {
       const nodes = [document.getElementById('h2-1'), document.getElementById('p1')];
       const wrapper = wrapNodesWithHighlight(nodes);
@@ -70,12 +79,15 @@ describe('highlight-heading-plus-sibling-nodes', () => {
       expect(wrapper.contains(nodes[0])).toBe(true);
       expect(wrapper.contains(nodes[1])).toBe(true);
     });
+    // Test: Does the system handle empty input gracefully?
     it('returns null if nodes is empty', () => {
       expect(wrapNodesWithHighlight([])).toBeNull();
     });
   });
 
+  // Tests for cleaning up existing highlights
   describe('removeExistingHighlights', () => {
+    // Test: Can the system remove highlights and restore original content structure?
     it('removes all .highlight2 wrappers and restores children', () => {
       const nodes = [document.getElementById('h2-1'), document.getElementById('p1')];
       wrapNodesWithHighlight(nodes);
@@ -89,24 +101,30 @@ describe('highlight-heading-plus-sibling-nodes', () => {
     });
   });
 
+  // Tests for the main highlighting functionality
   describe('highlightHeadingSection', () => {
+    // Test: Can the system highlight a section when given a valid anchor?
     it('highlights section for valid anchor', () => {
       expect(highlightHeadingSection('#h2-1')).toBe(true);
       const highlight = document.querySelector('.highlight2');
       expect(highlight).not.toBeNull();
       expect(highlight.contains(document.getElementById('h2-1'))).toBe(true);
     });
+    // Test: Does the system properly reject invalid anchors?
     it('returns false for invalid anchor', () => {
       expect(highlightHeadingSection('#does-not-exist')).toBe(false);
       expect(highlightHeadingSection('not-a-hash')).toBe(false);
       expect(highlightHeadingSection('#')).toBe(false);
     });
+    // Test: Does the system only work with heading elements?
     it('returns false for non-heading element', () => {
       expect(highlightHeadingSection('#p1')).toBe(false);
     });
   });
 
+  // Tests for setting up automatic highlighting based on URL anchors
   describe('initializeAnchorHighlighting', () => {
+    // Test: Does the system automatically highlight sections based on URL hash changes?
     it('sets up event listeners and highlights on hash', () => {
       window.location.hash = '#h2-1';
       // Remove highlights if any

package/assets/js/insert-trefs.js

@@ -7,7 +7,7 @@
 /**
  * Inserts transcluded external references (trefs) into the document.
  * This function processes the allXTrefs data and inserts definition content into the document
- * for terms marked with the 'transcluded-xref-term' class.
+ * for terms marked with the 'term-external' class.
  * @param {Object} allXTrefs - The object containing all external references data
  * @param {Array} allXTrefs.xtrefs - Array of external reference objects, each containing term definitions
  */
@@ -28,10 +28,21 @@ function insertTrefs(allXTrefs) {
        */
       const allTerms = [];
 
-      document.querySelectorAll('dl.terms-and-definitions-list dt span.transcluded-xref-term').forEach((termElement) => {
+      document.querySelectorAll('dl.terms-and-definitions-list dt span.term-external').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();
+         // const textContent = termElement.textContent.trim();
+
+         /*
+            We used to do this: Get the full text content including any nested spans (for aliases) of a term (dt):
+            `const textContent = termElement.textContent.trim();`
+            (In case of `[[tref:toip1, agency, ag]]`, this will return `agency`)
+
+            We cannot use the textContent directly anymore because it may not match the original term, since that can be the alias. That is why we use data-original-term.
+            In case of `[[tref:toip1, agency, ag]]`, this will always return `agency`, regardless if the alias is used or not, since the original term is stored in data-original-term
+         */
+         const originalTerm = termElement.dataset.originalTerm;
 
          // Find the dt element once outside the loop
          const dt = termElement.closest('dt');
@@ -39,7 +50,7 @@ function insertTrefs(allXTrefs) {
          // Skip if the term has already been processed
          if (dt) {
             const nextElement = dt.nextElementSibling;
-            if (nextElement?.classList.contains('transcluded-xref-term') &&
+            if (nextElement?.classList.contains('term-external') &&
                nextElement.classList.contains('meta-info-content-wrapper')) {
                return; // Already processed
             }
@@ -48,7 +59,7 @@ function insertTrefs(allXTrefs) {
          // Only add terms that haven't been processed yet
          allTerms.push({
             element: termElement,
-            textContent: textContent,
+            textContent: originalTerm,
             dt: dt,
             parent: dt?.parentNode
          });
@@ -60,21 +71,21 @@ function insertTrefs(allXTrefs) {
        * @type {Array<{dt: Element, parent: Element, fragment: DocumentFragment}>}
        */
       const domChanges = allTerms.map(termData => {
-         const { textContent, dt, parent } = termData;
+         const { textContent: originalTerm, dt, parent } = termData;
 
          if (!dt || !parent) {
             return null; // Skip invalid entries
          }
 
          // Find the first matching xref to avoid duplicates
-         const xref = xtrefsData.xtrefs.find(x => x.term === textContent);
-         
+         const xref = xtrefsData.xtrefs.find(x => x.term === originalTerm);
+
          // Create a DocumentFragment to hold all new elements for this term
          const fragment = document.createDocumentFragment();
 
          // Create meta info element
          const metaInfoEl = document.createElement('dd');
-         metaInfoEl.classList.add('transcluded-xref-term', 'meta-info-content-wrapper', 'collapsed');
+         metaInfoEl.classList.add('term-external', 'meta-info-content-wrapper', 'collapsed');
 
          if (xref) {
             // Generate meta info content
@@ -82,10 +93,13 @@ function insertTrefs(allXTrefs) {
             const owner = xref.owner || 'Unknown';
             const repo = xref.repo && xref.repoUrl ? `[${xref.repo}](${xref.repoUrl})` : 'Unknown';
             const commitHash = xref.commitHash || 'Unknown';
+            const linkToOriginalTerm = xref.ghPageUrl ? new URL(`#term:${xref.term}`, xref.ghPageUrl).href : 'Unknown';
 
             const metaInfo = `
 | Property | Value |
 | -------- | ----- |
+| Original Term | ${originalTerm} |
+| Link | ${linkToOriginalTerm} |
 | Owner | ${avatar} ${owner} |
 | Repo | ${repo} |
 | Commit hash | ${commitHash} |
@@ -102,10 +116,45 @@ function insertTrefs(allXTrefs) {
                .replace(/\]\]/g, '');
 
             // 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
+            // Part B: Remove some <a> elements from the content. We can turn the fact that the inserted URLs are relative (which previously seemed to be a disadvantage) into an advantage, since the fact that the URL then points to a possible local variant is actually an advantage. To this end, if the local variant does indeed exist, we leave the link intact.
             const tempDivForLinks = document.createElement('div');
             tempDivForLinks.innerHTML = md.render(content);
-            tempDivForLinks.querySelectorAll('a').forEach(a => a.replaceWith(...a.childNodes));
+            tempDivForLinks.querySelectorAll('a').forEach(a => {
+               // Helper function to safely check if an element exists by ID
+               // This handles IDs with special characters (like colons) that are invalid in CSS selectors
+               const elementExistsById = (id) => {
+                  try {
+                     return document.getElementById(id) !== null;
+                  } catch {
+                     return false;
+                  }
+               };
+
+               try {
+                  const url = new URL(a.href);
+                  
+                  // Keep links to different domains
+                  if (url.hostname !== window.location.hostname) {
+                     return;
+                  }
+                  
+                  // Keep links with valid local hash anchors
+                  if (url.hash && elementExistsById(url.hash.slice(1))) {
+                     return;
+                  }
+                  
+                  // Remove links to same domain without valid hash
+                  a.replaceWith(...a.childNodes);
+               } catch {
+                  // Handle relative URLs or invalid URL formats
+                  if (a.href.startsWith('#') && elementExistsById(a.href.slice(1))) {
+                     return;
+                  }
+                  
+                  // Remove invalid or non-local links
+                  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
@@ -120,7 +169,7 @@ function insertTrefs(allXTrefs) {
                   // Clone the node to avoid removing it from tempDiv during insertion
                   const clonedDD = dd.cloneNode(true);
                   // Add necessary classes
-                  clonedDD.classList.add('transcluded-xref-term', 'transcluded-xref-term-embedded');
+                  clonedDD.classList.add('term-external', 'term-external-embedded');
                   // Add to fragment
                   fragment.appendChild(clonedDD);
                });
@@ -130,7 +179,7 @@ function insertTrefs(allXTrefs) {
                   `"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.classList.add('term-external', 'term-external-embedded');
                contentEl.innerHTML = tempDiv.innerHTML;
                fragment.appendChild(contentEl);
             }

package/assets/js/mermaid-diagrams.js

@@ -0,0 +1,11 @@
+(function () {
+  'use strict';
+
+  /* Mermaid Diagrams */
+
+  mermaid.initialize({
+    startOnLoad: true,
+    theme: 'neutral'
+  });
+
+})();

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

@@ -0,0 +1,107 @@
+# Terminology Section Utility Container
+
+This directory contains the modular components for the terminology section utility container functionality.
+
+## Architecture
+
+The architecture follows a clear separation of concerns:
+
+- **DOM Construction**: All layout and structure in `../terminology-section-utility-container.js`
+- **Functionality**: Individual behavior modules in this directory
+
+## Structure
+
+```text
+terminology-section-utility-container/
+├── README.md                                      # This documentation
+├── hide-show-utility-container.js                # Removes container when no terms
+├── create-alphabet-index.js                      # Alphabet navigation functionality  
+├── create-term-filter.js                         # Local/Remote filter functionality
+└── search.js                                     # Search functionality
+```
+
+## Main Module (`../terminology-section-utility-container.js`)
+
+The main coordination module contains:
+
+### DOM Construction Section
+Complete layout definition in one place:
+
+```text
+/* ===== ROW 1: ALPHABET INDEX ===== */
+- Bootstrap row/col structure
+- Alphabet navigation buttons
+- Sorted character links
+
+/* ===== ROW 2: UTILITIES ===== */  
+- Term count display
+- Local/Remote filter checkboxes
+- Search input with navigation buttons
+- Matches counter
+```
+
+### Functionality Coordination
+Calls the individual modules:
+
+1. `attachAlphabetIndexFunctionality()`
+2. `attachTermFilterFunctionality(checkboxesContainer)`
+3. `attachSearchFunctionality(searchInput, prevBtn, nextBtn, counter)`
+
+## Sub-Modules (Functionality Only)
+
+Each module receives DOM elements as parameters and attaches behavior:
+
+### `create-alphabet-index.js`
+- Currently minimal (standard anchor links)
+- Ready for future enhancements (smooth scroll, analytics)
+
+### `create-term-filter.js`
+- Checkbox change event handling
+- "At least one checked" enforcement logic
+- HTML class toggling for hide/show terms
+
+### `search.js`
+- Input event handling with debouncing
+- Text highlighting and regex matching
+- Keyboard navigation (Arrow keys)
+- Match counting and navigation
+
+## Dependencies
+
+All modules depend on:
+
+- Bootstrap 5.3+ (for styling classes)
+- `specConfig` global object (for search styling configuration)
+
+## Usage
+
+The modules are automatically loaded and initialized via the asset compilation process. The main module coordinates everything when the DOM is ready.
+
+## Layout Result
+
+**Row 1 (Alphabet):**
+
+```text
+[A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]
+```
+
+**Row 2 (Controls):**
+
+```text
+25 terms    ☑ Local  ☑ Remote    [🔍 Search] [0 matches] [▲] [▼]
+```
+
+## Benefits of This Architecture
+
+✅ **Layout Visibility**: Complete DOM structure visible in one file  
+✅ **Modular Logic**: Functionality separated by concern  
+✅ **Maintainability**: Easy to modify layout or individual behaviors  
+✅ **Testability**: Functions receive dependencies as parameters  
+✅ **Reusability**: Logic modules could be used elsewhere  
+
+## Maintenance Notes
+
+- Order in `asset-map.json` matters: functionality modules before main module
+- All modules use traditional function declarations for Gulp compatibility
+- DOM elements are passed as parameters to avoid tight coupling
+- Bootstrap classes are used extensively to minimize custom CSS

package/assets/js/terminology-section-utility-container/create-alphabet-index.js

@@ -0,0 +1,17 @@
+/**
+ * @file Alphabet index functionality
+ * @author Kor Dwarshuis
+ * @version 1.0.0
+ * @since 2024-08-31
+ * @description Handles alphabet navigation functionality (DOM is constructed in main module)
+ */
+
+/**
+ * Attaches functionality to the alphabet index
+ * @returns {void}
+ */
+function attachAlphabetIndexFunctionality() {
+    // Currently, alphabet links are just standard anchor links
+    // Functionality can be added here in the future if needed
+    // (e.g., smooth scrolling, analytics tracking, etc.)
+}

package/assets/js/{create-term-filter.js → terminology-section-utility-container/create-term-filter.js}

@@ -1,14 +1,18 @@
 /**
- * @file This file creates an alphabet index for the terms
+ * @file Term filter functionality
  * @author Kor Dwarshuis
- * @version 0.0.1
- * @since 2024-09-19
+ * @version 1.0.0
+ * @since 2024-08-31
+ * @description Handles Local/Remote term filtering logic (DOM is constructed in main module)
  */
-function createTermFilter() {
+
+/**
+ * Attaches functionality to the term filter checkboxes
+ * @param {HTMLElement} checkboxesContainer - The container with the checkboxes
+ * @returns {void}
+ */
+function attachTermFilterFunctionality(checkboxesContainer) {
     // Check if the terms and definitions list exists
-    // If it doesn't exist, exit the function
-    // This prevents errors when the script is run on pages without the terms and definitions list
-    // and ensures that the script only runs when necessary
     const termsListElement = document.querySelector(".terms-and-definitions-list");
     const dtElements = termsListElement ? termsListElement.querySelectorAll("dt") : [];
 
@@ -16,36 +20,6 @@ function createTermFilter() {
         return;
     }
 
-    const terminologySectionUtilityContainer = document.getElementById("terminology-section-utility-container");
-
-    // Create checkboxes container
-    const checkboxesContainer = document.createElement('div');
-    checkboxesContainer.className = 'd-flex mt-0';
-    
-    // Create and configure checkbox for local terms
-    const localTermsCheckboxDiv = document.createElement('div');
-    localTermsCheckboxDiv.className = 'form-check me-3';
-    localTermsCheckboxDiv.innerHTML = `
-        <input class="form-check-input" type="checkbox" id="showLocalTermsCheckbox" checked>
-        <label class="form-check-label" for="showLocalTermsCheckbox">
-            Show local terms
-        </label>
-    `;
-    
-    // Create and configure checkbox for external terms
-    const externalTermsCheckboxDiv = document.createElement('div');
-    externalTermsCheckboxDiv.className = 'form-check ms-3';
-    externalTermsCheckboxDiv.innerHTML = `
-        <input class="form-check-input" type="checkbox" id="showExternalTermsCheckbox" checked>
-        <label class="form-check-label" for="showExternalTermsCheckbox">
-            Show external terms
-        </label>
-    `;
-    
-    // Append checkboxes to container
-    checkboxesContainer.appendChild(localTermsCheckboxDiv);
-    checkboxesContainer.appendChild(externalTermsCheckboxDiv);
-
     // Add event listeners to checkboxes (generic for any number of checkboxes)
     function enforceAtLeastOneChecked(event) {
         const checkboxes = checkboxesContainer.querySelectorAll('input[type="checkbox"]');
@@ -81,11 +55,4 @@ function createTermFilter() {
             enforceAtLeastOneChecked(event);
         }
     });
-
-    // Add checkboxes to the terminology section utility container
-    terminologySectionUtilityContainer.appendChild(checkboxesContainer);
 }
-
-document.addEventListener("DOMContentLoaded", function () {
-    createTermFilter();
-});

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

@@ -0,0 +1,21 @@
+/**
+ * @file Hides the utility container when no terms exist
+ * @author Kor Dwarshuis
+ * @version 1.0.0
+ * @since 2024-08-31
+ * @description Removes the utility container if no terms and definitions are present
+ */
+
+/**
+ * Hides the utility container if no terms exist
+ * @returns {void}
+ */
+function hideShowUtilityContainer() {
+    // 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) {
+        document.getElementById("terminology-section-utility-container")?.remove();
+    }
+}