spec-up-t 1.1.53 → 1.1.54

package/assets/js/create-alphabet-index.js

@@ -30,7 +30,14 @@ function createAlphabetIndex() {
     numberOfTerms.textContent = `– There are ${dtElements.length} terms –`;
 
     terminologySectionUtilityContainer.appendChild(numberOfTerms);
-    Object.keys(alphabetIndex).sort().forEach(char => {
+
+    /*
+        The key advantage of localeCompare over simple comparison operators (<, >) is that it:
+        - Properly handles language-specific sorting rules (via locale settings)
+        - Correctly compares strings containing special characters or accents
+        - Can be configured to be case-insensitive
+    */
+    Object.keys(alphabetIndex).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())).forEach(char => {
         const link = document.createElement("a");
         link.href = `#${alphabetIndex[char]}`;
         link.textContent = char;

package/branches.md

@@ -16,6 +16,15 @@
 Hierbij wordt de hele repository gedownload. Dit is een experiment om te kijken of ik de hele repository kan downloaden en dan de bestanden kan gebruiken die ik nodig heb. In plaats van de search API te gebruiken met zijn strakke limieten.
 
 
+## fix/ordering
+
+De volgorde van de termen. Hoofdletter kleine letter probleem
+
+## fix/xtref
+
+Tref creeren via index.html
+
+
 ## test/fixtref
 
 Bewaren, maar kan weg als ik uiteindelijk een andere oplossing heb gevonden.

package/index.js

@@ -102,7 +102,15 @@ module.exports = async function (options = {}) {
     function renderRefGroup(type) {
       let group = specGroups[type];
       if (!group) return '';
-      let html = Object.keys(group).sort().reduce((html, name) => {
+
+      /*
+        The key advantage of localeCompare over simple comparison operators (<, >) is that it:
+
+        - Properly handles language-specific sorting rules (via locale settings)
+        - Correctly compares strings containing special characters or accents
+        - Can be configured to be case-insensitive
+      */
+      let html = Object.keys(group).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())).reduce((html, name) => {
         let ref = group[name];
         return html += `
         <dt id="ref:${name}">${name}</dt>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.1.53",
+  "version": "1.1.54",
   "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/markdown-it-extensions.js

@@ -94,6 +94,111 @@ 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 = [];
+
+      // 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;
+            }
+          }
+        }
+      }
+
+      // 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;
+          }
+        }
+
+        // Replace the old tokens with the new sorted ones
+        tokens.splice(idx, newTokens.length, ...newTokens);
+      }
+      // END Sort terms and definitions alphabetically
     }
 
     let lastDdIndex = -1;