spec-up-t 1.2.4 → 1.2.6

package/assets/js/insert-trefs.js

@@ -1,21 +1,31 @@
 /**
- * @fileoverview Handles the insertion of transcluded external references (xrefs) into HTML documentation.
+ * @fileoverview Handles the insertion of transcluded external references (trefs) into HTML documentation.
  * This script processes terms marked with a specific class and adds their definitions from external sources.
+ * The terms come from external repositories and are inserted into the document as collapsible definitions.
  */
 
 /**
- * Inserts transcluded external references into the document.
+ * 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.
  * @param {Object} allXTrefs - The object containing all external references data
  * @param {Array} allXTrefs.xtrefs - Array of external reference objects, each containing term definitions
  */
-function insertTrefs(allXTrefs) { // Pass allXTrefs as a parameter
+function insertTrefs(allXTrefs) {
    /**
-    * Processes all terms found in the document and inserts their corresponding content
+    * Processes all terms found in the document and collects DOM changes
+    * before applying them in batch to improve performance.
+    * 
     * @param {Object} xtrefsData - The object containing xtrefs data
     * @param {Array} xtrefsData.xtrefs - Array of external reference objects
+    * @returns {void} - This function does not return a value but dispatches a 'trefs-inserted' event
+    * when all DOM modifications are complete
     */
    function processTerms(xtrefsData) {
-      // First collect all terms to ensure consistent processing order
+      /**
+       * First collect all terms to ensure consistent processing order
+       * @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)
@@ -23,22 +33,10 @@ function insertTrefs(allXTrefs) { // Pass allXTrefs as a parameter
             .map(node => node.textContent.trim())
             .join('');
 
-         allTerms.push({
-            element: termElement,
-            textContent: textContent
-         });
-      });
-
-      // Then process all terms in a consistent order (from the JS file order)
-      allTerms.forEach(termData => {
-         const termElement = termData.element;
-         const textContent = termData.textContent;
-
-         // Find the first matching xref to avoid duplicates
-         const xref = xtrefsData.xtrefs.find(x => x.term === textContent);
-
-         // Skip if we've already added content for this term (check for existing dd elements)
+         // Find the dt element once outside the loop
          const dt = termElement.closest('dt');
+
+         // Skip if the term has already been processed
          if (dt) {
             const nextElement = dt.nextElementSibling;
             if (nextElement?.classList.contains('transcluded-xref-term') &&
@@ -47,13 +45,38 @@ function insertTrefs(allXTrefs) { // Pass allXTrefs as a parameter
             }
          }
 
-         if (xref) {
-            const parent = dt.parentNode;
+         // Only add terms that haven't been processed yet
+         allTerms.push({
+            element: termElement,
+            textContent: textContent,
+            dt: dt,
+            parent: dt?.parentNode
+         });
+      });
+
+      /**
+       * Prepare all DOM changes first before making any insertions
+       * Each item in the array contains the elements needed for DOM insertion
+       * @type {Array<{dt: Element, parent: Element, fragment: DocumentFragment}>}
+       */
+      const domChanges = allTerms.map(termData => {
+         const { textContent, 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);
+
+         // Create a DocumentFragment to hold all new elements for this term
+         const fragment = document.createDocumentFragment();
 
-            // Create and insert meta info element
-            const metaInfoEl = document.createElement('dd');
-            metaInfoEl.classList.add('transcluded-xref-term', 'meta-info-content-wrapper', 'collapsed');
+         // Create meta info element
+         const metaInfoEl = document.createElement('dd');
+         metaInfoEl.classList.add('transcluded-xref-term', 'meta-info-content-wrapper', 'collapsed');
 
+         if (xref) {
             // Generate meta info content
             const avatar = xref.avatarUrl ? `![avatar](${xref.avatarUrl})` : '';
             const owner = xref.owner || 'Unknown';
@@ -68,7 +91,7 @@ function insertTrefs(allXTrefs) { // Pass allXTrefs as a parameter
 | Commit hash | ${commitHash} |
             `;
             metaInfoEl.innerHTML = md.render(metaInfo);
-            parent.insertBefore(metaInfoEl, dt.nextSibling);
+            fragment.appendChild(metaInfoEl);
 
             // Clean up markdown content
             let content = xref.content
@@ -83,67 +106,129 @@ function insertTrefs(allXTrefs) { // Pass allXTrefs as a parameter
             const tempDiv = document.createElement('div');
             tempDiv.innerHTML = md.render(content);
 
-            // If there are dd elements in the rendered content, insert them directly
+            // If there are dd elements in the rendered content, prepare them for insertion
             const ddElements = tempDiv.querySelectorAll('dd');
             if (ddElements.length > 0) {
-               // Insert each dd element in the correct order
-               let insertPosition = metaInfoEl; // Start inserting after the meta info element
-               
-               // Convert NodeList to Array and insert in original order
+               // Add all dd elements to the fragment in original order
                Array.from(ddElements).forEach(dd => {
                   // 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');
-                  // Insert after the previous element
-                  parent.insertBefore(clonedDD, insertPosition.nextSibling);
-                  // Update insertion position to be after this newly inserted element
-                  insertPosition = clonedDD;
+                  // Add to fragment
+                  fragment.appendChild(clonedDD);
                });
             } else {
                // No dd elements found, create one to hold the content
                const contentEl = document.createElement('dd');
                contentEl.classList.add('transcluded-xref-term', 'transcluded-xref-term-embedded');
                contentEl.innerHTML = tempDiv.innerHTML;
-               parent.insertBefore(contentEl, metaInfoEl.nextSibling);
+               fragment.appendChild(contentEl);
             }
          } else {
             // Handle case where xref is not found
-            const parent = dt.parentNode;
-
-            // Create and insert meta info for not found case
-            const metaInfoEl = document.createElement('dd');
-            metaInfoEl.classList.add('transcluded-xref-term', 'meta-info-content-wrapper', 'collapsed');
-            const metaInfo = `
+            metaInfoEl.innerHTML = md.render(`
 | Property | Value |
 | -------- | ----- |
 | Owner | Unknown |
 | Repo | Unknown |
 | Commit hash | not found |
-            `;
-            metaInfoEl.innerHTML = md.render(metaInfo);
-            parent.insertBefore(metaInfoEl, dt.nextSibling);
+            `);
+            fragment.appendChild(metaInfoEl);
 
-            // Create and insert not found message
+            // 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>';
-            parent.insertBefore(notFoundEl, metaInfoEl.nextSibling);
+            fragment.appendChild(notFoundEl);
          }
+
+         // Return all necessary information for DOM insertion
+         return {
+            dt: dt,
+            parent: parent,
+            fragment: fragment
+         };
+      }).filter(Boolean); // Remove null entries
+
+      /**
+       * Perform all DOM insertions in a single batch using requestAnimationFrame
+       * to optimize browser rendering and prevent layout thrashing
+       */
+      requestAnimationFrame(() => {
+         domChanges.forEach(change => {
+            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 } 
+         }));
       });
    }
-   
 
    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' } 
+      }));
    }
 }
 
+/**
+ * Handles the initialization of collapsible definitions functionality.
+ * This function sets up event listeners for the 'trefs-inserted' event and 
+ * provides a fallback initialization mechanism if the event is never fired.
+ * @param {Function} initCallback - The function to call when initialization should occur
+ * @returns {void} - This function does not return a value
+ */
+function initializeOnTrefsInserted(initCallback) {
+   // Track initialization state
+   let hasInitialized = false;
+
+   // Set up the event listener for the custom event from insert-trefs.js
+   document.addEventListener('trefs-inserted', function (event) {
+      // Avoid double initialization
+      if (hasInitialized) return;
+
+      // Now we know for certain that insert-trefs.js has completed its work
+      hasInitialized = true;
+      initCallback();
+
+      // Log info about the completed xrefs insertion (useful for debugging)
+      if (event.detail) {
+         console.log(`Collapsible definitions initialized after ${event.detail.count} xrefs were inserted`);
+      }
+   });
+
+   // Fallback initialization in case insert-trefs.js doesn't run or doesn't emit the event
+   // This ensures our UI works even if there's an issue with xrefs processing
+   // or if the 'trefs-inserted' event is never dispatched for some reason
+
+   // Wait for a reasonable time, then check if we've initialized
+   setTimeout(() => {
+      if (!hasInitialized) {
+         console.warn('trefs-inserted event was not received, initializing collapsible definitions anyway');
+         initCallback();
+         hasInitialized = true;
+      }
+   }, 1000); // Longer timeout as this is just a fallback
+}
+
 /**
  * Initialize the transcluded references when the DOM is fully loaded.
  * Checks for the global allXTrefs object and calls insertTrefs if available.
+ * This event listener ensures that the DOM is ready before attempting to process references.
+ * @listens DOMContentLoaded
  */
 document.addEventListener('DOMContentLoaded', () => {
    // Check if allXTrefs is defined in the global scope
@@ -152,4 +237,5 @@ document.addEventListener('DOMContentLoaded', () => {
    } else {
       console.warn('allXTrefs is not available in the global scope. Transcluded references will not be inserted.');
    }
-});
+});
+

package/assets/js/search.js

@@ -14,13 +14,25 @@
 */
 
 function inPageSearch() {
+   // 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") : [];
+
+   if (dtElements.length === 0) {
+      return;
+   }
+
+
    /*****************/
    /* CONFIGURATION */
 
    const terminologySectionUtilityContainer = document.getElementById("terminology-section-utility-container");
 
    const matchesStyle = specConfig.searchHighlightStyle || 'ssi';
-   const antiNameCollisions = 'search-h7vc6omi2hr2880';// random string to be added to classes, id's etc, to prevent name collisions in the global space
+   const antiNameCollisions = 'search';
    const debounceTime = 600;
    const matches = 'matches';// What text to display after the number of matches
    const searchBarPlaceholder = '🔍';
@@ -31,12 +43,12 @@ function inPageSearch() {
 
    // Styling of search matches. See styles in /assets/css/search.css
    const matchesStyleSelector = {
-      dif: 'highlight-matches-DIF-search-h7vc6omi2hr2880',
-      toip: 'highlight-matches-ToIP-search-h7vc6omi2hr2880',
-      btc: 'highlight-matches-BTC-search-h7vc6omi2hr2880',
-      keri: 'highlight-matches-KERI-search-h7vc6omi2hr2880',
-      ssi: 'highlight-matches-SSI-search-h7vc6omi2hr2880',
-      gleif: 'highlight-matches-GLEIF-search-h7vc6omi2hr2880'
+      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'
    };
 
 
@@ -101,13 +113,15 @@ function inPageSearch() {
 
    // Add an event listener to the input element
    searchInput.addEventListener("input", function () {
-      debouncedSearchAndHighlight(searchInput.value);
+      const shouldScrollToFirstMatch = true; // Scroll to first match when user is actively searching
+      debouncedSearchAndHighlight(searchInput.value, shouldScrollToFirstMatch);
    });
 
    // The search will run when the user clicks the collapse button, so the search results are updated when the terms are collapsed or expanded. If the definitions are collapsed, the search results in the definitions will be removed.
    document.addEventListener('click', event => {
       if (event.target.classList.contains('collapse-all-defs-button')) {
-         debouncedSearchAndHighlight(searchInput.value);
+         const shouldScrollToFirstMatch = true; // Scroll when updating after collapse/expand
+         debouncedSearchAndHighlight(searchInput.value, shouldScrollToFirstMatch);
       }
    });
 
@@ -180,7 +194,11 @@ function inPageSearch() {
       totalMatchesSpan.innerHTML = `${totalMatches} ${matches}`;
    }
 
-   // Debounce search input. Prepare the debounced function outside the event listener
+   // Debounce search input to improve performance. This creates a function that will only execute
+   // after the user has stopped typing for the specified debounceTime.
+   // The function takes two parameters:
+   // - searchString: The text to search for
+   // - scrollToFirstMatch: Whether to automatically scroll to the first match after highlighting
    const debouncedSearchAndHighlight = debounce(search, debounceTime);
 
    goToPreviousMatchButton.addEventListener("click", function () {
@@ -231,7 +249,12 @@ function inPageSearch() {
    });
 
    // Runs after every search input (debounced)
-   function search(searchString) {
+   /**
+    * Performs search and highlighting of matches in the document
+    * @param {string} searchString - The text to search for
+    * @param {boolean} scrollToFirstMatch - Whether to automatically scroll to the first match after highlighting
+    */
+   function search(searchString, scrollToFirstMatch) {
       // Start clean
       removeAllSpans();
       totalMatches = 0;
@@ -240,8 +263,8 @@ function inPageSearch() {
       // Remove outer quotes if present
       if (searchString.length >= 2) {
          if (
-            (searchString[0] === '"' && searchString[searchString.length - 1] === '"') ||
-            (searchString[0] === "'" && searchString[searchString.length - 1] === "'")
+            (searchString.startsWith('"') && searchString.endsWith('"')) ||
+            (searchString.startsWith("'") && searchString.endsWith("'"))
          ) {
             searchString = searchString.substring(1, searchString.length - 1);
          }
@@ -316,13 +339,6 @@ function inPageSearch() {
 
       searchNodes(searchableContent);
 
-      // Scroll to the first match
-      // Using querySelector instead of querySelectorAll because we only want to select the first element
-      let firstHighlight = document.querySelector('.' + matchesStyleSelectorClassName);
-      if (firstHighlight !== null) {
-         scrollToElementCenter(firstHighlight);
-      }
-
       // Update the total matches counter
       setTotalMatches();
 
@@ -331,6 +347,16 @@ function inPageSearch() {
 
       // Update the active match index
       activeMatchIndex = -1;
+
+      // Scroll to the first match
+      // Using querySelector instead of querySelectorAll because we only want to select the first element
+      if (scrollToFirstMatch) {
+         let firstHighlight = document.querySelector('.' + matchesStyleSelectorClassName);
+         if (firstHighlight !== null) {
+            scrollToElementCenter(firstHighlight);
+      }
+   
+}
    }
 }
 

package/{src → config}/asset-map.json

@@ -23,6 +23,9 @@
       "assets/css/external-links.css",
       "assets/css/repo-issues.css",
       "assets/css/adjust-font-size.css",
+      "assets/css/image-full-size.css",
+      "assets/css/add-bootstrap-classes-to-images.css",
+      "assets/css/horizontal-scroll-hint.css",
       "assets/css/index.css"
     ],
     "js": [
@@ -44,6 +47,7 @@
       "assets/js/tippy.js",
       "assets/js/diff.min.js",
       "assets/js/edit-term-buttons.js",
+      "assets/js/hide-show-utility-container.js",
       "assets/js/create-alphabet-index.js",
       "assets/js/search.js",
       "assets/js/highlightMenuItems.js",
@@ -66,6 +70,8 @@
       "assets/js/close-off-canvas-menu.js",
       "assets/js/index.js",
       "assets/js/horizontal-scroll-hint.js",
+      "assets/js/add-bootstrap-classes-to-images.js",
+      "assets/js/image-full-size.js",
       "assets/js/bootstrap.bundle.min.js"
     ]
   }

package/{src/config → config}/paths.js

@@ -12,9 +12,9 @@ const paths = {};
 // console.log(getAllPaths());
 
 // Add paths
-paths['output-local-terms'] = path.resolve('output', 'local-terms-dir');
+paths['output-local-terms'] = path.resolve('.cache', 'local-terms-dir');
 paths['specsjson'] = path.resolve('specs.json');
-paths['githubcache'] = path.resolve('output', 'github-cache');
+paths['githubcache'] = path.resolve('.cache', 'github-cache');
 
 module.exports = {
     /**

package/gulpfile.js

@@ -11,7 +11,7 @@ const terser = require('gulp-terser');
 const mergeStreams = require('merge-stream');
 const cleanCSS = require('gulp-clean-css');
 const axios = require('axios').default;
-const assets = fs.readJsonSync('./src/asset-map.json');
+const assets = fs.readJsonSync('./config/asset-map.json');
 
 let compileLocation = 'assets/compiled';
 

package/index.js

@@ -25,7 +25,7 @@ module.exports = async function (options = {}) {
 
     const findPkgDir = require('find-pkg-dir');
     const modulePath = findPkgDir(__dirname);
-    let config = fs.readJsonSync('./output/specs-generated.json');
+    let config = fs.readJsonSync('./.cache/specs-generated.json');
 
     const createExternalSpecsList = require('./src/create-external-specs-list.js');
 
@@ -37,7 +37,7 @@ module.exports = async function (options = {}) {
     const { fixMarkdownFiles } = require('./src/fix-markdown-files.js');
 
     let template = fs.readFileSync(path.join(modulePath, 'templates/template.html'), 'utf8');
-    let assets = fs.readJsonSync(modulePath + '/src/asset-map.json');
+    let assets = fs.readJsonSync(modulePath + '/config/asset-map.json');
     let externalReferences;
     let references = [];
     let definitions = [];
@@ -218,7 +218,7 @@ module.exports = async function (options = {}) {
 
     function createScriptElementWithXTrefDataForEmbeddingInHtml() {
       // Test if xtrefs-data.js exists, else make it an empty string
-      const inputPath = path.join('output', 'xtrefs-data.js');
+      const inputPath = path.join('.cache', 'xtrefs-data.js');
 
       let xtrefsData = '';
       if (fs.existsSync(inputPath)) {
@@ -406,7 +406,7 @@ module.exports = async function (options = {}) {
         mainDl.className = 'terms-and-definitions-list';
 
         // Look for the marker
-        const marker = document.getElementById('terminology-section-start-h7vc6omi2hr2880');
+        const marker = document.getElementById('terminology-section-start');
 
         if (marker) {
           // Insert the new dl right after the marker
@@ -523,7 +523,7 @@ module.exports = async function (options = {}) {
         const termsIndex = (spec.markdown_paths || ['spec.md']).indexOf('terms-and-definitions-intro.md');
         if (termsIndex !== -1) {
           // Append the HTML string to the content of terms-and-definitions-intro.md. This string is used to create a div that is used to insert an alphabet index, and a div that is used as the starting point of the terminology index. The newlines are essential for the correct rendering of the markdown.
-          docs[termsIndex] += '\n\n<div id="terminology-section-start-h7vc6omi2hr2880"></div>\n\n';
+          docs[termsIndex] += '\n\n<div id="terminology-section-start"></div>\n\n';
         }
 
         let doc = docs.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Technical specification drafting tool that generates rich specification documents from markdown. Forked from https://github.com/decentralized-identity/spec-up by Daniel Buchner (https://github.com/csuwildcat)",
   "main": "./index",
   "repository": {

package/src/README.md

@@ -78,9 +78,9 @@
 <ul>
 <li>Creates three output files:
 <ul>
-<li><code>output/xtrefs-data.json</code> - JSON data file</li>
-<li><code>output/xtrefs-data.js</code> - JavaScript module file</li>
-<li><code>output/xtrefs-history/xtrefs-data-[timestamp].js</code> - Historical record</li>
+<li><code>.cache/xtrefs-data.json</code> - JSON data file</li>
+<li><code>.cache/xtrefs-data.js</code> - JavaScript module file</li>
+<li><code>.cache/xtrefs-history/xtrefs-data-[timestamp].js</code> - Historical record</li>
 </ul>
 </li>
 </ul>

package/src/collect-external-references.js

@@ -188,12 +188,12 @@ function processExternalReferences(config, GITHUB_API_TOKEN, options) {
     );
 
     // Ensure that the 'output' directory exists, creating it if necessary.
-    const outputDir = 'output';
+    const outputDir = '.cache';
     if (!fs.existsSync(outputDir)) {
         fs.mkdirSync(outputDir);
     }
 
-    // Ensure that the 'output/xtrefs-history' directory exists, creating it if necessary.
+    // Ensure that the 'xtrefs-history' in outputDir exists, creating it if necessary.
     const xtrefsHistoryDir = path.join(outputDir, 'xtrefs-history');
     if (!fs.existsSync(xtrefsHistoryDir)) {
         fs.mkdirSync(xtrefsHistoryDir);