spec-up-t 1.2.5 → 1.2.7

package/assets/js/collapse-definitions.js

@@ -1,52 +1,278 @@
+/**
+ * @fileoverview Manages collapsible definition lists with visual state indicators.
+ * @author Kor Dwarshuis
+ * @version 1.0.0
+ * @description This module provides functionality to toggle the visibility
+ * of definition descriptions in a document with a smooth user experience.
+ * It creates interactive buttons with three toggle states and prevents
+ * UI jumping during transitions using fixed positioning and requestAnimationFrame.
+ * @requires insert-trefs.js - For the initializeOnTrefsInserted helper function
+ */
+
+/**
+ * Sets up collapsible definition lists with toggle buttons.
+ * Handles the creation of buttons, event listeners, and visibility states.
+ * This is the main initialization function that's called when the DOM is ready
+ * and all transcluded references have been inserted.
+ * @function
+ * @see initializeOnTrefsInserted - Helper function that ensures this runs at the right time
+ */
 function collapseDefinitions() {
-    const dds = document.querySelectorAll('#content dl.terms-and-definitions-list > dd');
-    const dts = document.querySelectorAll('#content dl.terms-and-definitions-list > dt');
-    const buttons = document.querySelectorAll('.collapse-all-defs-button');
+    /**
+     * Queries and categorizes definition list elements in the DOM.
+     * @function
+     * @returns {Object} Object containing categorized DOM element collections
+     * @returns {NodeList} returns.dds - All definition descriptions
+     * @returns {NodeList} returns.dts - All definition terms
+     * @returns {Array<Element>} returns.regularDds - Standard definition descriptions
+     * @returns {Array<Element>} returns.specialDds - Special definition descriptions (e.g., "See also", "Source")
+     */
+    function queryElements() {
+        const dds = document.querySelectorAll('#content dl.terms-and-definitions-list > dd');
+        const dts = document.querySelectorAll('#content dl.terms-and-definitions-list > dt');
+        const regularDds = Array.from(dds).filter(dd => !isSpecialDefinition(dd.textContent.trim()));
+        const specialDds = Array.from(dds).filter(dd => isSpecialDefinition(dd.textContent.trim()));
+
+        return { dds, dts, regularDds, specialDds };
+    }
+
+    let { dds, dts, regularDds, specialDds } = queryElements();
+    const buttonTitleText = 'Change how much info is shown';
+
+    /**
+     * Determines if a definition is a special type (e.g., a "See also" or "Source" note)
+     * @param {string} content - The content of the definition to check
+     * @returns {boolean} True if the content starts with a special prefix
+     */
+    function isSpecialDefinition(content) {
+        const definitionHidePrefixes = [
+            "Source",
+            "See also",
+            "More in",
+            "Also see",
+            "See:",
+            "See also",
+            "See more",
+            "See more in",
+            "See more about",
+            "See more on",
+            "See more at",
+            "More:",
+            "Supporting definitions:"
+        ];
+        return definitionHidePrefixes.some(prefix => content.startsWith(prefix));
+    }
+
+    specialDds.forEach(dd => {
+        dd.classList.add('terms-def-extra-info');
+    });
 
+    /**
+     * Toggles the visibility state of definitions across the document.
+     * Cycles through three visibility states:
+     * - State 0: All definitions hidden
+     * - State 1: Only regular definitions visible
+     * - State 2: All definitions visible
+     * 
+     * Updates UI indicators to reflect the current state.
+     * @function
+     */
     function toggleVisibility() {
-        const isHidden = dds[0].classList.contains('hidden');
-        dds.forEach(dd => {
-            dd.classList.toggle('hidden', !isHidden);
-            dd.classList.toggle('visible', isHidden);
-        });
-        buttons.forEach(button => {
-            button.innerHTML = isHidden ? '▲' : '▼';
-            button.title = isHidden ? 'Collapse all definitions' : 'Expand all definitions';
+        const buttons = document.querySelectorAll('.collapse-all-defs-button');
+        const currentState = parseInt(buttons[0].dataset.state || 0);
+        // Cycle through 3 states: 0 (all hidden), 1 (only regular visible), 2 (all visible)
+        const newState = (currentState + 1) % 3;
+
+        // Update state based on newState
+        switch (newState) {
+            case 0: // All definitions hidden
+                dds.forEach(dd => {
+                    dd.classList.add('hidden');
+                    dd.classList.remove('visible');
+                });
+                buttons.forEach(button => {
+                    button.dataset.state = 0;
+                    button.title = 'Show basic definitions';
+                    // Update which state indicator is active
+                    button.querySelectorAll('.state-indicator').forEach(indicator => {
+                        if (parseInt(indicator.dataset.state) === 0) {
+                            indicator.classList.add('active');
+                        } else {
+                            indicator.classList.remove('active');
+                        }
+                    });
+                });
+                document.querySelector('html').classList.add('defs-hidden');
+                break;
+
+            case 1: // Only regular definitions visible
+                regularDds.forEach(dd => {
+                    dd.classList.remove('hidden');
+                    dd.classList.add('visible');
+                });
+                specialDds.forEach(dd => {
+                    dd.classList.add('hidden');
+                    dd.classList.remove('visible');
+                });
+                buttons.forEach(button => {
+                    button.dataset.state = 1;
+                    button.title = 'Show all definitions';
+                    // Update which state indicator is active
+                    button.querySelectorAll('.state-indicator').forEach(indicator => {
+                        if (parseInt(indicator.dataset.state) === 1) {
+                            indicator.classList.add('active');
+                        } else {
+                            indicator.classList.remove('active');
+                        }
+                    });
+                });
+                document.querySelector('html').classList.remove('defs-hidden');
+                break;
+
+            case 2: // All definitions visible
+                dds.forEach(dd => {
+                    dd.classList.remove('hidden');
+                    dd.classList.add('visible');
+                });
+                specialDds.forEach(dd => {
+                    dd.classList.add('terms-def-extra-info');
+                });
+                buttons.forEach(button => {
+                    button.dataset.state = 2;
+                    button.title = 'Hide all definitions';
+                    // Update which state indicator is active
+                    button.querySelectorAll('.state-indicator').forEach(indicator => {
+                        if (parseInt(indicator.dataset.state) === 2) {
+                            indicator.classList.add('active');
+                        } else {
+                            indicator.classList.remove('active');
+                        }
+                    });
+                });
+                document.querySelector('html').classList.remove('defs-hidden');
+                break;
+        }
+    }
+
+    /**
+     * Creates and appends toggle buttons to all definition terms.
+     * Each button contains state indicators for the three visibility states,
+     * and is initialized to show all definitions (state 2).
+     * @function
+     */
+    function addButtons() {
+        dts.forEach(dt => {
+            // Check if button already exists to avoid duplicates
+            if (dt.querySelector('.collapse-all-defs-button')) {
+                return; // Skip if button already exists
+            }
+
+            const button = document.createElement('button');
+            button.classList.add('collapse-all-defs-button', 'btn-outline-secondary', 'd-print-none', 'btn', 'p-0', 'fs-5', 'd-flex', 'align-items-center', 'justify-content-center');
+            // Create a container for all three state indicators
+            button.innerHTML = `<span class="state-indicator" data-state="0">①</span><span class="state-indicator" data-state="1">②</span><span class="state-indicator" data-state="2">③</span>`;
+            button.setAttribute('id', 'toggleButton');
+            button.setAttribute('title', buttonTitleText);
+            button.setAttribute('data-state', '2'); // Start with all definitions visible
+
+            // Set initial active state
+            button.querySelector('.state-indicator[data-state="2"]').classList.add('active');
+
+            dt.appendChild(button);
         });
-        document.querySelector('html').classList.toggle('defs-hidden');
     }
 
-    // Add button as last child of every <dl>
-    dts.forEach(dt => {
-        const button = document.createElement('button');
-        button.classList.add('collapse-all-defs-button', 'd-print-none', 'btn', 'p-0', 'fs-5', 'd-flex', 'align-items-center','justify-content-center');
-        button.innerHTML = '▲';
-        button.setAttribute('id', 'toggleButton');
-        dt.appendChild(button);
-    });
+    // Initial button setup
+    addButtons();
 
-    // Via event delegation add event listener to every .collapse-all-defs-button element
+    /**
+     * Handles click events on definition toggle buttons and their state indicators.
+     * Uses advanced positioning techniques to prevent UI jumping during transitions:
+     * 1. Temporarily fixes the button's position using position:fixed during DOM updates
+     * 2. Uses requestAnimationFrame for optimal timing of position restoration
+     * 3. Precisely adjusts scroll position to maintain visual stability
+     * 
+     * This prevents the visual disruption that would otherwise occur when expanding
+     * or collapsing definitions causes layout reflow.
+     * 
+     * @param {Event} event - The DOM click event
+     */
     document.addEventListener('click', event => {
-        if (event.target.classList.contains('collapse-all-defs-button')) {
-            toggleVisibility();
+        // Check if the click is on a state-indicator or the button itself
+        if (event.target.classList.contains('collapse-all-defs-button') ||
+            event.target.classList.contains('state-indicator')) {
+            // Get the button element (whether clicked directly or via child)
+            const button = event.target.classList.contains('collapse-all-defs-button') ?
+                event.target :
+                event.target.closest('.collapse-all-defs-button');
 
-            event.target.scrollIntoView({
-                behavior: 'smooth',
-                block: 'start',
-                inline: 'nearest'
-            });
+            // Find the parent dt and dl elements
+            const dtElement = button.closest('dt');
+
+            // Get button's position in viewport and page
+            const buttonRect = button.getBoundingClientRect();
 
-            // Adjust the scroll position by 100px smoothly
+            // Apply a class to prevent layout shifts during transition
+            document.documentElement.classList.add('definitions-transitioning');
+
+            /**
+             * Button position anchoring technique:
+             * 1. Fix the button in its current viewport position to ensure 
+             *    it doesn't move during DOM reflow
+             * 2. Apply fixed positioning with the exact same coordinates
+             * 3. After DOM changes, restore normal positioning and adjust scroll
+             */
+            button.style.position = 'fixed';
+            button.style.top = `${buttonRect.top}px`;
+            button.style.right = `${window.innerWidth - buttonRect.right}px`;
+            button.style.zIndex = '1000';
+
+            // Add highlight effect
+            dtElement.classList.add('highlight');
             setTimeout(() => {
-                window.scrollBy({
-                    top: -100,
-                    behavior: 'smooth'
+                dtElement.classList.remove('highlight');
+            }, 0);
+
+            // Toggle visibility which might change layout
+            toggleVisibility();
+
+            /**
+             * Visual stability restoration:
+             * Use requestAnimationFrame to restore normal positioning at the optimal time
+             * after DOM updates, when the browser is ready to paint the next frame.
+             * This provides better timing than setTimeout for visual operations.
+             */
+            requestAnimationFrame(() => {
+                // Remove fixed positioning
+                button.style.position = '';
+                button.style.top = '';
+                button.style.right = '';
+                button.style.zIndex = '';
+
+                // Remove the transitioning class
+                document.documentElement.classList.remove('definitions-transitioning');
+
+                // Scroll to correct position so the button appears where it was fixed
+                const newButtonRect = button.getBoundingClientRect();
+
+                // Calculate and apply precise scroll adjustment to maintain visual position
+                window.scrollTo({
+                    top: window.scrollY + (newButtonRect.top - buttonRect.top),
+                    behavior: 'instant'
                 });
-            }, 500); // Delay to ensure the initial scrollIntoView completes
+            });
         }
     });
 }
 
+/**
+ * Initialize the collapsible definitions functionality when the DOM is fully loaded.
+ * We listen for a custom event from insert-trefs.js to know exactly when all
+ * external references have been inserted into the DOM.
+ * @listens DOMContentLoaded - Standard DOM event fired when initial HTML document is completely loaded
+ * @listens trefs-inserted - Custom event fired by insert-trefs.js when all term references are processed
+ * @see initializeOnTrefsInserted - Helper function that manages initialization timing
+ */
 document.addEventListener("DOMContentLoaded", function () {
-    collapseDefinitions();
+    initializeOnTrefsInserted(collapseDefinitions);
 });

package/assets/js/collapse-meta-info.js

@@ -5,25 +5,30 @@
  * @since 2025-02-16
  */
 
-// Function to create the toggle button
+/**
+ * Creates a toggle button for collapsible meta information sections.
+ * @function createToggleButton
+ * @param {HTMLElement} element - The DD element that contains the meta information
+ * @returns {void}
+ */
 function createToggleButton(element) {
     const toggleButton = document.createElement('button');
     toggleButton.classList.add('meta-info-toggle-button', 'btn');
     toggleButton.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 16 16" style="shape-rendering: geometricPrecision;">' +
         '<path fill-rule="evenodd" d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>' +
-        '<path d="M8.93 6.588l-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588z"/>' + 
+        '<path d="M8.93 6.588l-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588z"/>' +
         '<path d="M9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>' +
-    '</svg>';
+        '</svg>';
     toggleButton.title = 'Meta info';
 
     // Add event listener to the button
-    toggleButton.addEventListener('click', function(e) {
+    toggleButton.addEventListener('click', function (e) {
         e.preventDefault();
         e.stopPropagation();
-        
+
         // Get the wrapper containing the meta info
         const isCollapsed = element.classList.contains('collapsed');
-        
+
         // Toggle the collapsed state
         if (isCollapsed) {
             // If collapsed, expand it
@@ -49,14 +54,20 @@ function createToggleButton(element) {
     }
 }
 
-// Find all elements with class 'collapsible' and make them collapsible
-document.addEventListener('DOMContentLoaded', function() {
+
+/**
+ * Finds all description list items (dd) that contain tables and makes them collapsible.
+ * Adds necessary wrapper elements and toggle buttons to create the collapsible UI.
+ * @function collapseMetaInfo
+ * @returns {void}
+ */
+function collapseMetaInfo() {
     const collapsibles = document.querySelectorAll('dl > dd:has(table)');
 
-    collapsibles.forEach(function(element) {
+    collapsibles.forEach(function (element) {
         // Add meta-info-content-wrapper class
         element.classList.add('meta-info-content-wrapper');
-        
+
         // Wrap content in a div for proper spacing
         const wrapper = document.createElement('div');
         wrapper.classList.add('meta-info-inner-wrapper');
@@ -75,4 +86,20 @@ document.addEventListener('DOMContentLoaded', function() {
         // Collapse by default on load
         element.classList.add('collapsed');
     });
+}
+
+
+/**
+ * Initialize the collapse meta info functionality when the DOM is fully loaded.
+ * We use the initializeOnTrefsInserted helper from insert-trefs.js to ensure our 
+ * functionality runs at the right time - either after all external references have
+ * been inserted, or after a timeout if the event isn't triggered.
+ * 
+ * @listens DOMContentLoaded - Initial event when DOM is ready
+ * @listens trefs-inserted - Custom event from insert-trefs.js when all external references are inserted
+ * @see initializeOnTrefsInserted - Helper function that manages initialization timing
+ */
+document.addEventListener("DOMContentLoaded", function () {
+    initializeOnTrefsInserted(collapseMetaInfo);
 });
+

package/assets/js/collapsibleMenu.js

@@ -98,35 +98,11 @@ function initCollapsibleMenu() {
       }
     }
   });
-  
-  console.log('Collapsible menu initialized with accessibility improvements');
-}
-
-// Log TOC structure to help debugging
-function logTOCStructure() {
-  const tocContainer = document.getElementById('toc');
-  if (tocContainer) {
-    console.log('TOC container found:', tocContainer);
-    console.log('TOC container children:', tocContainer.children);
-    const firstUL = tocContainer.querySelector('ul');
-    if (firstUL) {
-      console.log('First UL found:', firstUL);
-      console.log('UL class list:', firstUL.classList);
-      const listItems = firstUL.querySelectorAll('li');
-      console.log('List items count:', listItems.length);
-    } else {
-      console.warn('No UL found in TOC container');
-    }
-  } else {
-    console.warn('TOC container not found');
-  }
 }
 
 // Run after DOM is fully loaded
 document.addEventListener('DOMContentLoaded', () => {
   initCollapsibleMenu();
-  // Log the TOC structure for debugging
-  logTOCStructure();
 });
 
 // Re-initialize when highlighting changes

package/assets/js/create-term-filter.js

@@ -16,7 +16,6 @@ function createTermFilter() {
         return;
     }
 
-
     const terminologySectionUtilityContainer = document.getElementById("terminology-section-utility-container");
 
     // Create checkboxes container
@@ -43,27 +42,46 @@ function createTermFilter() {
         </label>
     `;
     
-    // Add event listeners to checkboxes
-    localTermsCheckboxDiv.querySelector('#showLocalTermsCheckbox').addEventListener('change', function(event) {
+    // 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"]');
+        const checkedBoxes = Array.from(checkboxes).filter(cb => cb.checked);
+        // If the user is unchecking a box
         if (!event.target.checked) {
-            document.querySelector('html').classList.add('hide-local-terms');
-        } else {
-            document.querySelector('html').classList.remove('hide-local-terms');
+            // If all others are already unchecked (so this would make all unchecked except the one being unchecked)
+            if (checkedBoxes.length === 0) {
+                // Check all other checkboxes except the one being unchecked
+                checkboxes.forEach(cb => {
+                    if (cb !== event.target) {
+                        cb.checked = true;
+                    }
+                });
+                // The one being unchecked remains unchecked
+            }
         }
-    });
-    
-    externalTermsCheckboxDiv.querySelector('#showExternalTermsCheckbox').addEventListener('change', function(event) {
-        if (!event.target.checked) {
-            document.querySelector('html').classList.add('hide-external-terms');
-        } else {
-            document.querySelector('html').classList.remove('hide-external-terms');
+        // Toggle classes for each checkbox type
+        checkboxes.forEach(cb => {
+            const html = document.querySelector('html');
+            if (cb.id === 'showLocalTermsCheckbox') {
+                html.classList.toggle('hide-local-terms', !cb.checked);
+            } else if (cb.id === 'showExternalTermsCheckbox') {
+                html.classList.toggle('hide-external-terms', !cb.checked);
+            }
+            // Add more else ifs here for future checkboxes
+        });
+    }
+
+    // Attach the handler to all checkboxes in the container
+    checkboxesContainer.addEventListener('change', function(event) {
+        if (event.target.matches('input[type="checkbox"]')) {
+            enforceAtLeastOneChecked(event);
         }
     });
-    
-    // Append checkboxes to container
-    checkboxesContainer.appendChild(localTermsCheckboxDiv);
-    checkboxesContainer.appendChild(externalTermsCheckboxDiv);
-    
+
     // Add checkboxes to the terminology section utility container
     terminologySectionUtilityContainer.appendChild(checkboxesContainer);
 }

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

@@ -8,7 +8,6 @@ function hideShowUtilityContainer() {
 
    if (dtElements.length === 0) {
       document.getElementById("terminology-section-utility-container")?.remove();
-      // document.getElementById("terminology-section-utility-container")?.style.display = "none";
    }
 }
 

package/assets/js/horizontal-scroll-hint.js

@@ -113,7 +113,7 @@ const horizontalScrollHint = (elements) => {
         // Create scroll hint element
         const scrollHint = document.createElement('p');
         scrollHint.classList.add('scrollHint');
-        scrollHint.innerHTML = `<img style='width: 40px; vertical-align: middle;' src='${fingerHorizontalScrollingImage}' alt='finger scrolling horizontally' /> Scroll to the right`;
+        scrollHint.innerHTML = `<img class='scrollHintImage' style='width: 40px; vertical-align: middle; padding: 0;margin: 0 !important;' src='${fingerHorizontalScrollingImage}' alt='' /> Scroll to the right`;
         scrollHint.style.animation = 'arrow-tweet-panel-pulse 0.82s ease-in-out infinite';
 
         el.appendChild(scrollHint);
@@ -155,5 +155,5 @@ document.addEventListener("DOMContentLoaded", function () {
   // Apply to multiple different elements
   // horizontalScrollHint(['.table-container', '.code-block', document.querySelector('#special-element')]);
 
-  horizontalScrollHint(['.table-responsive']);
+  horizontalScrollHint(['.table-responsive-md']);
 });

package/assets/js/image-full-size.js

@@ -19,8 +19,6 @@ const imageFullSize = () => {
   }
 
   if (markdownElement) {
-    console.log("event listener added");
-    
     markdownElement.addEventListener('click', (event) => {
       if (event.target.tagName === 'IMG') {