spec-up-t 1.1.54 → 1.2.0

package/src/markdown-it-extensions.js

@@ -7,6 +7,49 @@ const contentRegex = /\s*([^\s\[\]:]+):?\s*([^\]\n]+)?/i;
 
 module.exports = function (md, templates = {}) {
 
+  // Add table renderer to apply Bootstrap classes to all tables by default
+  const originalTableRender = md.renderer.rules.table_open || function (tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  // Save the original table_close renderer
+  const originalTableCloseRender = md.renderer.rules.table_close || function (tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  // Override table_open to add both the classes and open a wrapper div
+  md.renderer.rules.table_open = function (tokens, idx, options, env, self) {
+    // Add Bootstrap classes to the table element
+    const token = tokens[idx];
+    const classIndex = token.attrIndex('class');
+    const tableClasses = 'table table-striped table-bordered table-hover';
+    
+    if (classIndex < 0) {
+      token.attrPush(['class', tableClasses]);
+    } else {
+      // If a class attribute already exists, append our classes
+      const existingClasses = token.attrs[classIndex][1];
+      // Only add classes that aren't already present
+      const classesToAdd = tableClasses
+        .split(' ')
+        .filter(cls => !existingClasses.includes(cls))
+        .join(' ');
+      
+      if (classesToAdd) {
+        token.attrs[classIndex][1] = existingClasses + ' ' + classesToAdd;
+      }
+    }
+    
+    // Add the responsive wrapper div before the table
+    return '<div class="table-responsive">' + originalTableRender(tokens, idx, options, env, self);
+  };
+
+  // Override table_close to close the wrapper div
+  md.renderer.rules.table_close = function (tokens, idx, options, env, self) {
+    // Close the table and add the closing div
+    return originalTableCloseRender(tokens, idx, options, env, self) + '</div>';
+  };
+
   md.inline.ruler.after('emphasis', 'templates', function templates_ruler(state, silent) {
 
     var start = state.pos;
@@ -78,7 +121,6 @@ module.exports = function (md, templates = {}) {
   let classAdded = false;
 
   md.renderer.rules.dl_open = function (tokens, idx, options, env, self) {
-
     const targetHtml = 'terminology-section-start-h7vc6omi2hr2880';
     let targetIndex = -1;
 
@@ -94,115 +136,35 @@ module.exports = function (md, templates = {}) {
     if (targetIndex !== -1 && idx > targetIndex && !classAdded) {
       tokens[idx].attrPush(['class', 'terms-and-definitions-list']);
       classAdded = true;
+    }
 
-      /* Sort terms and definitions alphabetically
-      Sort dt/dd pairs case-insensitively based on dt content
-
-      1: Token-based Markdown Processing: Spec-Up-T uses a token-based approach to parse and render Markdown. When Markdown is processed, it's converted into a series of tokens that represent different elements (like dt_open, dt_content, dt_close, dd_open, dd_content, dd_close). We're not dealing with simple strings but with structured tokens.
-
-      2: Preserving Relationships: When sorting terms, we need to ensure that each definition term (<dt>) stays connected to its corresponding definition description (<dd>). It's not as simple as sorting an array of strings - we're sorting complex structures.
-
-      3: Implementation Details: The implementation includes:
-
-      - Finding the terminology section in the document
-      - Collecting term starts, ends, and their contents
-      - Creating a sorted index based on case-insensitive comparisons
-      - Rebuilding the token array in the correct order
-      - Ensuring all relationships between terms and definitions are preserved
-      - Handling special cases and edge conditions
-
-      The complexity is unavoidable because:
-
-      - We're working with the markdown-it rendering pipeline, not just manipulating DOM
-      - The terms and definitions exist as tokens before they become HTML
-      - We need to preserve all the token relationships while reordering
-      - We're intercepting the rendering process to modify the token structure
-
-      If we were just sorting DOM elements after the page rendered, it would be simpler. But by doing the sorting during the Markdown processing, we ensure the HTML output is correct from the beginning, which is more efficient and leads to better performance.
-      */
-      let dtStartIndices = [];
-      let dtEndIndices = [];
-      let dtContents = [];
+    let lastDdIndex = -1;
+    let currentDtIndex = -1; // Track current dt to detect empty dt elements
 
-      // First pass: collect all dt blocks and their contents
-      for (let i = idx + 1; i < tokens.length; i++) {
-        if (tokens[i].type === 'dl_close') {
-          break;
-        }
-        if (tokens[i].type === 'dt_open') {
-          const startIdx = i;
-          let content = '';
-
-          // Find the end of this dt block and capture its content
-          for (let j = i + 1; j < tokens.length; j++) {
-            if (tokens[j].type === 'dt_close') {
-              dtStartIndices.push(startIdx);
-              dtEndIndices.push(j);
-              dtContents.push(content.toLowerCase()); // Store lowercase for case-insensitive sorting
-              break;
-            }
-            // Collect the content inside the dt (including spans with term IDs)
-            if (tokens[j].content) {
-              content += tokens[j].content;
-            }
-          }
-        }
+    // First pass - check for and mark empty dt elements
+    // This scan identifies definition terms that have no content (empty dt elements)
+    // which is one of the root causes of the issues we're fixing
+    for (let i = idx + 1; i < tokens.length; i++) {
+      if (tokens[i].type === 'dl_close') {
+        break;
       }
-
-      // Create indices sorted by case-insensitive term content
-      const sortedIndices = dtContents.map((_, idx) => idx)
-        .sort((a, b) => dtContents[a].localeCompare(dtContents[b]));
-
-      // Reorder the tokens based on the sorted indices
-      if (sortedIndices.length > 0) {
-        // Create a new array of tokens
-        const newTokens = tokens.slice(0, idx + 1); // Include dl_open
-
-        // For each dt/dd pair in sorted order
-        for (let i = 0; i < sortedIndices.length; i++) {
-          const originalIndex = sortedIndices[i];
-          const dtStart = dtStartIndices[originalIndex];
-          const dtEnd = dtEndIndices[originalIndex];
-
-          // Add dt tokens
-          for (let j = dtStart; j <= dtEnd; j++) {
-            newTokens.push(tokens[j]);
-          }
-
-          // Find and add dd tokens
-          let ddFound = false;
-          for (let j = dtEnd + 1; j < tokens.length; j++) {
-            if (tokens[j].type === 'dt_open' || tokens[j].type === 'dl_close') {
-              break;
-            }
-            if (tokens[j].type === 'dd_open') {
-              ddFound = true;
-            }
-            if (ddFound) {
-              newTokens.push(tokens[j]);
-              if (tokens[j].type === 'dd_close') {
-                break;
-              }
-            }
-          }
-        }
-
-        // Add the closing dl token
-        for (let i = idx + 1; i < tokens.length; i++) {
-          if (tokens[i].type === 'dl_close') {
-            newTokens.push(tokens[i]);
-            break;
-          }
+      
+      if (tokens[i].type === 'dt_open') {
+        currentDtIndex = i;
+        // Check if this is an empty dt (no content between dt_open and dt_close)
+        // An empty dt is when a dt_close token immediately follows a dt_open token
+        if (i + 1 < tokens.length && tokens[i + 1].type === 'dt_close') {
+          // Mark this dt pair for handling by adding an isEmpty property
+          // This property will be used later to skip rendering these empty elements
+          tokens[i].isEmpty = true;
+          tokens[i + 1].isEmpty = true;
         }
-
-        // Replace the old tokens with the new sorted ones
-        tokens.splice(idx, newTokens.length, ...newTokens);
       }
-      // END Sort terms and definitions alphabetically
     }
 
-    let lastDdIndex = -1;
-
+    // Second pass - add classes and handle last-dd
+    // Now that we've identified empty dt elements, we can process the tokens
+    // while skipping the empty ones
     for (let i = idx + 1; i < tokens.length; i++) {
       if (tokens[i].type === 'dl_close') {
         // Add class to the last <dd> before closing <dl>
@@ -219,6 +181,12 @@ module.exports = function (md, templates = {}) {
       }
 
       if (tokens[i].type === 'dt_open') {
+        // Skip empty dt elements - this is where we use the isEmpty flag
+        // to avoid processing empty definition terms
+        if (tokens[i].isEmpty) {
+          continue; // Skip to the next iteration without processing this empty dt
+        }
+        
         // Add class to the last <dd> before a new <dt>
         if (lastDdIndex !== -1) {
           const ddToken = tokens[lastDdIndex];
@@ -239,4 +207,67 @@ module.exports = function (md, templates = {}) {
 
     return originalRender(tokens, idx, options, env, self);
   };
+  
+  // Override the rendering of dt elements to properly handle transcluded terms
+  const originalDtRender = md.renderer.rules.dt_open || function (tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+  
+  md.renderer.rules.dt_open = function (tokens, idx, options, env, self) {
+    // Skip rendering empty dt elements - this is the first critical fix
+    // When a dt has been marked as empty, we return an empty string
+    // instead of rendering the <dt> tag. This effectively removes empty dt tags
+    // from the output HTML.
+    if (tokens[idx].isEmpty) {
+      return '';
+    }
+    
+    // Check if this dt is part of a transcluded term by looking at the next inline token
+    // This is part of the second fix, to properly handle transcluded terms
+    let isTranscluded = false;
+    for (let i = idx + 1; i < tokens.length; i++) {
+      if (tokens[i].type === 'dt_close') {
+        break;
+      }
+      // Look for child tokens that are template tokens with type 'tref'
+      // These represent transcluded terms from external sources
+      if (tokens[i].type === 'inline' && 
+          tokens[i].children && 
+          tokens[i].children.some(child => 
+            child.type === 'template' && 
+            child.info && 
+            child.info.type === 'tref')) {
+        isTranscluded = true;
+        break;
+      }
+    }
+    
+    // Add a class for transcluded terms to ensure proper styling
+    // This helps maintain consistent styling for transcluded terms
+    if (isTranscluded) {
+      const classIndex = tokens[idx].attrIndex('class');
+      if (classIndex < 0) {
+        tokens[idx].attrPush(['class', 'transcluded-xref-term']);
+      } else {
+        tokens[idx].attrs[classIndex][1] += ' transcluded-xref-term';
+      }
+    }
+    
+    return originalDtRender(tokens, idx, options, env, self);
+  };
+  
+  // Similarly override dt_close to skip empty dts
+  const originalDtCloseRender = md.renderer.rules.dt_close || function (tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+  
+  md.renderer.rules.dt_close = function (tokens, idx, options, env, self) {
+    // Skip rendering the closing </dt> tag for empty dt elements
+    // This completes the fix for empty dt elements by ensuring neither
+    // the opening nor closing tags are rendered
+    if (tokens[idx].isEmpty) {
+      return '';
+    }
+    return originalDtCloseRender(tokens, idx, options, env, self);
+  };
 };

package/src/prepare-tref.js

@@ -26,23 +26,40 @@ const { shouldProcessFile } = require('./utils/file-filter');
 
 function getLocalXTrefContent(externalSpec, term) {
     const filePath = path.join('output', 'xtrefs-data.json');
-    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    const xtrefs = data.xtrefs;
-
-    for (const xtref of xtrefs) {
-        if (xtref.externalSpec === externalSpec && xtref.term === term) {
-            return {
-                content: xtref.content,
-                commitHash: xtref.commitHash,
-                owner: xtref.owner,
-                repo: xtref.repo,
-                repoUrl: xtref.repoUrl,
-                avatarUrl: xtref.avatarUrl
-            };
+    
+    try {
+        const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        const xtrefs = data.xtrefs;
+
+        for (const xtref of xtrefs) {
+            if (xtref.externalSpec === externalSpec && xtref.term === term) {
+                // Validate that required properties exist
+                if (!xtref.content || !xtref.owner || !xtref.repo || !xtref.repoUrl) {
+                    console.warn(`Warning: Incomplete data for ${externalSpec}, ${term}`);
+                }
+                
+                return {
+                    content: xtref.content || "No content available",
+                    commitHash: xtref.commitHash || "Not available",
+                    owner: xtref.owner || "Unknown",
+                    repo: xtref.repo || "Unknown",
+                    repoUrl: xtref.repoUrl || "#",
+                    avatarUrl: xtref.avatarUrl || ""
+                };
+            }
         }
+    } catch (err) {
+        console.error(`Error reading xtrefs-data.json: ${err}`);
     }
 
-    return null;
+    return {
+        content: `Term '${term}' not found in external specification '${externalSpec}'`,
+        commitHash: "Not available",
+        owner: "Unknown",
+        repo: "Unknown",
+        repoUrl: "#",
+        avatarUrl: ""
+    };
 }
 
 // Function to process markdown files in a directory recursively
@@ -93,18 +110,34 @@ function prepareTref(directory) {
                             if (lines[i].startsWith('[[tref:')) {
                                 const tref = /\[\[tref:(.*?)\]\]/;
                                 const match = lines[i].match(tref);
+                                let currentTref = lines[i]; // Store the current tref line for error handling
+                                
                                 if (match) {
-                                    const result = match[1].split(',').map(term => term.trim());
-                                    const localXTrefContent = getLocalXTrefContent(result[0], result[1]);
-
-                                    const defPart = /\[\[def: ([^,]+),.*?\]\]/g;
-                                    localXTrefContent.content = localXTrefContent.content.replace(defPart, '');
-
-                                    const readyForWrite = dedent`
+                                    try {
+                                        const result = match[1].split(',').map(term => term.trim());
+                                        
+                                        if (result.length < 2) {
+                                            throw new Error(`Invalid tref format. Expected: [[tref:spec,term]], got: ${match[0]}`);
+                                        }
+                                        
+                                        const localXTrefContent = getLocalXTrefContent(result[0], result[1]);
+                                        
+                                        // Skip processing if essential data is missing
+                                        if (!localXTrefContent) {
+                                            console.warn(`Warning: No content found for ${result[0]}, ${result[1]}`);
+                                            continue;
+                                        }
+                                        
+                                        const defPart = /\[\[def: ([^,]+),.*?\]\]/g;
+                                        if (localXTrefContent.content) {
+                                            localXTrefContent.content = localXTrefContent.content.replace(defPart, '');
+                                        }
+
+                                        const readyForWrite = dedent`
 ${match[0]}
 | Property | Value |
 | -------- | ----- |
-| Owner | ![avatar](${localXTrefContent.avatarUrl}) ${localXTrefContent.owner} |
+| Owner | ${localXTrefContent.avatarUrl ? `![avatar](${localXTrefContent.avatarUrl})` : ''} ${localXTrefContent.owner} |
 | Repo | [${localXTrefContent.repo}](${localXTrefContent.repoUrl}) |
 | Commit hash | ${localXTrefContent.commitHash} |
 
@@ -115,12 +148,16 @@ ${contentAfterSpan}
 
 `;
 
-                                    fs.writeFileSync(itemPath, readyForWrite, 'utf8');
+                                        fs.writeFileSync(itemPath, readyForWrite, 'utf8');
+                                    } catch (err) {
+                                        console.error(`Error processing tref: ${err}`);
+                                        fs.writeFileSync(itemPath, currentTref + '\n\n' + '\n\nError processing reference: ' + err.message, 'utf8');
+                                    }
                                 }
                             }
                         }
                     } catch (err) {
-                        fs.writeFileSync(itemPath, match[0] + '\n\n' + '\n\nNothing found, so nothing to show.', 'utf8');
+                        console.error(`Error processing file ${itemPath}: ${err}`);
                     }
                 }
             });

package/src/utils/fetch.js

@@ -0,0 +1,100 @@
+/**
+ * Utility functions to fetch and parse various JSON specification files
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Fetches the output/specs-generated.json file and returns it as a JavaScript object
+ * @returns {Object} The parsed contents of specs-generated.json
+ */
+function fetchSpecs() {
+  try {
+    // Resolve path to output/specs-generated.json from the project root
+    const specsPath = path.resolve(process.cwd(), 'output', 'specs-generated.json');
+    
+    // Read the file synchronously
+    const specsContent = fs.readFileSync(specsPath, 'utf8');
+    
+    // Parse the JSON content
+    const specs = JSON.parse(specsContent);
+    
+    return specs;
+  } catch (error) {
+    console.error('Error fetching output/specs-generated.json:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Fetches the output/xtrefs-data.json file and returns it as a JavaScript object
+ * @returns {Object} The parsed contents of xtrefs-data.json
+ */
+function fetchExternalTerms() {
+  try {
+    // Resolve path to output/xtrefs-data.json from the project root
+    const xtrefsPath = path.resolve(process.cwd(), 'output', 'xtrefs-data.json');
+    
+    // Read the file synchronously
+    const xtrefsContent = fs.readFileSync(xtrefsPath, 'utf8');
+    
+    // Parse the JSON content
+    const xtrefs = JSON.parse(xtrefsContent);
+    
+    return xtrefs;
+  } catch (error) {
+    console.error('Error fetching output/xtrefs-data.json:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Asynchronous version of fetchGeneratedSpecs
+ * @returns {Promise<Object>} The parsed specs-generated object
+ */
+async function fetchSpecsAsync() {
+  try {
+    // Resolve path to output/specs-generated.json from the project root
+    const specsPath = path.resolve(process.cwd(), 'output', 'specs-generated.json');
+    
+    // Read the file asynchronously
+    const specsContent = await fs.promises.readFile(specsPath, 'utf8');
+    
+    // Parse the JSON content
+    const specs = JSON.parse(specsContent);
+    
+    return specs;
+  } catch (error) {
+    console.error('Error fetching output/specs-generated.json:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Asynchronous version of fetchXtrefsData
+ * @returns {Promise<Object>} The parsed xtrefs-data object
+ */
+async function fetchExternalTermsAsync() {
+  try {
+    // Resolve path to output/xtrefs-data.json from the project root
+    const xtrefsPath = path.resolve(process.cwd(), 'output', 'xtrefs-data.json');
+    
+    // Read the file asynchronously
+    const xtrefsContent = await fs.promises.readFile(xtrefsPath, 'utf8');
+    
+    // Parse the JSON content
+    const xtrefs = JSON.parse(xtrefsContent);
+    
+    return xtrefs;
+  } catch (error) {
+    console.error('Error fetching output/xtrefs-data.json:', error.message);
+    return null;
+  }
+}
+
+module.exports = {
+  fetchSpecs,
+  fetchSpecsAsync,
+  fetchExternalTerms,
+  fetchExternalTermsAsync
+};

package/templates/template.html

@@ -109,7 +109,7 @@
 
     <header id="header" class="navbar sticky-top p-0 shadow">
         <!-- Left-aligned elements -->
-        <button class="nav-link px-3 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#sidebarMenu"
+        <button class="nav-link d-print-none px-3 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#sidebarMenu"
             aria-controls="sidebarMenu" aria-expanded="false" aria-label="Toggle navigation">
             <svg class="bi">
                 <use xlink:href="#list" />
@@ -117,7 +117,7 @@
         </button>
 
         <a id="logo" href="${specLogoLink}">
-            <img class="m-1" src="${specLogo}" alt="" />
+            <img class="d-print-none m-1" src="${specLogo}" alt="" />
         </a>
         <!-- <a class="navbar-brand col-md-3 col-lg-2 me-0 px-3 fs-6 text-white" href="#">Spec-Up-T</a> -->
 
@@ -125,7 +125,7 @@
         <div class="flex-grow-1"></div>
 
         <!-- Right-aligned elements -->
-        <div class="d-flex align-items-center">
+        <div class="d-flex align-items-center service-menu d-print-none">
 
             <!-- Settings side menu -->
             <button id="repo_settings" animate class="btn btn-sm btn-outline-secondary ms-2" type="button"
@@ -137,7 +137,7 @@
             </button>
 
             <!-- Dark / Light theme selector -->
-            <div class="dropdown bd-mode-toggle me-2">
+            <div class="dropdown bd-mode-toggle">
                 <button
                     class="btn btn-bd-primary btn-sm btn-outline-secondary dropdown-toggle d-flex align-items-center"
                     id="bd-theme" type="button" aria-expanded="false" data-bs-toggle="dropdown"
@@ -175,13 +175,18 @@
                 </ul>
             </div>
 
+            <!-- Container width toggle -->
+            <button id="container_toggle" title="Toggle wide/narrow layout" type="button" class="btn btn-sm btn-outline-secondary me-2">
+                <span class="visually-hidden">Toggle wide/narrow layout</span>
+                <i class="bi bi-arrows-angle-expand"></i>
+            </button>
+
             <!-- Font size -->
             <div class="adjust-font-size btn-group me-2" role="group">
                 <button title="Decrease font size" type="button"
                     class="btn btn-outline-secondary m-0 border-end-0" id="decreaseBtn"><span
                         class="visually-hidden">Decrease font size</span>
                 </button>
-                <!-- <button type="button" class="btn btn-sm btn-outline-secondary m-0 px-2" id="resetBtn">0</button> -->
                 <button title="Increase font size" type="button"
                     class="btn btn-outline-secondary m-0 border-start-0" id="increaseBtn">
                     <span class="visually-hidden">Increase font size</span>
@@ -192,7 +197,7 @@
 
     <div class="container">
         <div class="row">
-            <div class="sidebar border border-right col-md-4 col-lg-3 bg-body-tertiary">
+            <div class="sidebar d-print-none border border-right col-md-4 col-lg-3 bg-body-tertiary">
                 <div class="offcanvas-md offcanvas-start bg-body-tertiary p-2 pt-5" tabindex="-1" id="sidebarMenu"
                     aria-labelledby="sidebarMenuLabel">
                     <div class="offcanvas-header">
@@ -210,7 +215,7 @@
 
             <main class="col-md-8 ms-sm-auto col-lg-9 px-md-4 pt-5">
                 <article id="content" class="">
-                    <div id="terminology-section-utility-container" class="alert alert-primary p-3"></div>
+                    <div id="terminology-section-utility-container" class="d-print-none alert alert-primary p-3"></div>
                     ${render}
                 </article>
 

package/assets/js/css-helper.js

@@ -1,30 +0,0 @@
-/*
-    JS to help with CSS.
-*/
-
-function addClassToTranscludedTerms() {
-    // Find all spans with class 'transcluded-xref-term'
-    const spans = document.querySelectorAll('span.transcluded-xref-term');
-
-    spans.forEach(span => {
-        // Find the closest <dt> ancestor
-        const dt = span.closest('dt');
-        if (dt) {
-            // Add class 'transcluded-xref-term' to the <dt>
-            dt.classList.add('transcluded-xref-term');
-
-            // Get the next sibling elements until the next <dt> or </dl>
-            let sibling = dt.nextElementSibling;
-            while (sibling && sibling.tagName !== 'DT' && sibling.tagName !== 'DL') {
-                if (sibling.tagName === 'DD') {
-                    sibling.classList.add('transcluded-xref-term');
-                }
-                sibling = sibling.nextElementSibling;
-            }
-        }
-    });
-}
-
-document.addEventListener("DOMContentLoaded", function () {
-    addClassToTranscludedTerms();
-});