rdoc-babel 1.2.0 → 1.4.0

data/lib/rdoc/generator/ruby-lang/scripts/indexFrame.js

@@ -1,5 +1,12 @@
+/*
+  Script for the left iframe.
+*/
 
-document.addEventListener('DOMContentLoaded', function () {
+// CSS must be loaded before finding the geography of indexes
+// document.addEventListener('DOMContentLoaded', function () {
+window.addEventListener('load', function () {
+
+  // --- class for index info
 
   // the info about an index block
   // index blocks are like this:
@@ -44,6 +51,7 @@ document.addEventListener('DOMContentLoaded', function () {
         const style = window.getComputedStyle(this.list);
         const listHeightPadding = parseFloat(style.paddingTop) + parseFloat(style.paddingBottom);
         this.entries = this.list.getElementsByTagName('p');
+        this.links = this.list.getElementsByTagName('a');
         this.entryCount = this.entries.length;
         // height of one entry
         const listRect = this.list.getBoundingClientRect();
@@ -58,10 +66,12 @@ document.addEventListener('DOMContentLoaded', function () {
         this.searchBox = null;
         this.list = null;
         this.entries = [];
+        this.links = [];
         this.entryCount = 0;
         this.entryHeight = 0;
         this.fixedHeight = 0;
       }
+      // height of this index before the current resize
       this.prevHeight = null;
     }
 
@@ -72,14 +82,14 @@ document.addEventListener('DOMContentLoaded', function () {
         return 0;
     }
 
+    // enough room for 2 entries
     get minHeight() {
       return this.fixedHeight + 2 * this.entryHeight;
     }
 
     setHeight(height, { resetPrev = false } = {}) {
       if (!this.div) return;
-      // floor multiple of 0.01
-      const h = (~~((height - this.fixedHeight) * 100)) / 100;
+      const h = height - this.fixedHeight;
       if (this.prevHeight === null || resetPrev) {
         // no previous or reset asked: set prev = current
         this.list.style.height = `${h}px`;
@@ -92,58 +102,185 @@ document.addEventListener('DOMContentLoaded', function () {
       }
     }
 
+    // save the layout of this index, including the search text
+    saveInfo(storage) {
+      if (!this.div) return;
+      storage.setItem(`${this.name}Index.prevHeight`, this.prevHeight);
+      storage.setItem(`${this.name}Index.styleHeight`, this.list.style.height);
+      storage.setItem(`${this.name}Index.scrollTop`, this.list.scrollTop);
+      if (this.searchBox) {
+        storage.setItem(`${this.name}Index.searchWidth`, this.searchBox.style.width);
+        storage.setItem(`${this.name}Index.searchText`, this.searchBox.value || '');
+      }
+    }
+
+    // restore a previously saved layout & search text
+    restoreInfo(storage) {
+      if (!this.div) return;
+      this.prevHeight = storage.getItem(`${this.name}Index.prevHeight`);
+      this.list.style.height = storage.getItem(`${this.name}Index.styleHeight`);
+      this.list.scrollTop = storage.getItem(`${this.name}Index.scrollTop`);
+      if (this.searchBox) {
+        this.searchBox.style.width = storage.getItem(`${this.name}Index.searchWidth`);
+        this.searchBox.value = storage.getItem(`${this.name}Index.searchText`);
+      }
+    }
+
+    // highlight the entry for <a> aNode and make sure it is visible
+    setCurrent(aNode) {
+      for (const a of this.links)
+        if (a === aNode) {
+          a.classList.add('current-main');
+          this.ensureVisible(a);
+        }
+        else
+          a.classList.remove('current-main');
+    }
+
+    ensureVisible(a) {
+      const aTopOffset = a.offsetTop - this.links[0].offsetTop;
+      const aHeight = a.getBoundingClientRect().height;
+      const offScreen =
+        // not (completely) visible because above
+        aTopOffset < this.list.scrollTop ||
+        // not (completely) visible because below
+        aTopOffset + aHeight > this.list.scrollTop + this.list.clientHeight
+      ;
+      // position in the middle of the list
+      if (offScreen)
+        this.list.scrollTop = aTopOffset - this.list.clientHeight / 2;
+    }
+
   }
 
+  // --- global setup
+
   const fileIndex = new Index('file');
   const classIndex = new Index('class');
   const methodIndex = new Index('method');
 
   setupResizing();
-  setupSearches();
-  setupHighlighting();
+
+  // --- setup the vertical resizing of indexes by dragging
 
   const fileClassResizer = document.getElementById('file-class-resizer');   // may be null
   const classMethodResizer = document.getElementById('class-method-resizer');
 
-  frameResized(true);
+  if (!restoreLayoutInfo())
+    frameResized(true);
+  setupSearches();
 
   if (fileClassResizer)
     fileClassResizer.addEventListener('mousedown', function(e) {startDrag(e, fileIndex, classIndex)});
   classMethodResizer.addEventListener('mousedown', function(e) {startDrag(e, classIndex, methodIndex)});
 
-  // handle highlighting in main frame when the document
-  // in the main frame does not change
-  function highlightTarget(e) {
-    // this is relative:
-    var target_href = e.target.getAttribute('href');
-    // this is absolute:
-    var current_href = top.mainFrame.location.href;
-    var parts = target_href.split('#');
-    var target_path = parts[0];
-    var target_id = parts[1];
-    var current_path = top.mainFrame.location.pathname;
-    var i = current_path.length - target_path.length;
-    var x = current_path.substring(i);
-    if (i > 0 && current_path.substring(i) == target_path)
-      highlightElement(target_id);
+  // --- highlight of the current file/class/method
+
+  highlightCurrentIndexEntries();
+
+  function highlightCurrentIndexEntries() {
+
+    // /C:/docs/ruby/32/core/files/toc_core_md.html
+    // /C:/docs/ruby/32/core/classes/Process.html
+    const currentPath = window.parent.location.pathname;
+    const index = (currentPath.indexOf('/classes/') < 0) ? fileIndex : classIndex;
+
+    for (const a of index.links) {
+      const href = a.getAttribute('href');
+      if (currentPath.endsWith(href)) {
+        index.setCurrent(a);
+        break;
+      }
+    }
+
+    if (index === fileIndex)
+      return;
+
+    setCurrentMethod(currentPath);
+  }
+
+  function setCurrentMethod(currentPath) {
+    const hash = window.parent.location.hash;
+    if (!hash) return;
+
+    const currentMethod = `${currentPath}${hash}`;
+    for (const a of methodIndex.links) {
+      const href = a.getAttribute('href');
+      if (currentMethod.endsWith(href)) {
+        methodIndex.setCurrent(a);
+        break;
+      }
+    }
+  }
+
+  // --- when clicking on a link, remember the scroll positions & search state of each index
+
+  for (const a of fileIndex.links)
+    a.addEventListener('click', saveLayoutInfo);
+  for (const a of classIndex.links)
+    a.addEventListener('click', saveLayoutInfo);
+  for (const a of methodIndex.links)
+    a.addEventListener('click', saveLayoutInfo);
+
+  function saveLayoutInfo(e) {
+    const s = window.parent.sessionStorage;
+    s.setItem('infoSaved', 'true');
+
+    // the width of the left frame
+    const width = window.parent.document.getElementById('left-container').style.width;
+    s.setItem('left.frameWidth', width);
+
+    // position of the left frame resizer
+    const left = window.parent.document.getElementById('resizer').style.left;
+    s.setItem('left.resizerLeft', left);
+
+    // the height & position of each index
+    fileIndex.saveInfo(s);
+    classIndex.saveInfo(s);
+    methodIndex.saveInfo(s);
+  }
+
+  // restores the saved layout and returns true, or returns false if no saved layout
+  function restoreLayoutInfo() {
+    // restore previous scroll positions & search states if any
+    const s = window.parent.sessionStorage;
+    const saved = s.getItem(`infoSaved`);
+    if (saved) {
+      window.parent.document.getElementById('left-container').style.width = s.getItem('left.frameWidth');
+      window.parent.document.getElementById('resizer').style.left = s.getItem('left.resizerLeft');
+      fileIndex.restoreInfo(s);
+      classIndex.restoreInfo(s);
+      methodIndex.restoreInfo(s);
+      placeResizers();
+    }
+    return saved === 'true';
+  }
+
+  // --- when navigating inside the same main document, handle current method highlighting
+
+  window.parent.addEventListener('hashchange', mainHashChanged);
+
+  // highlight the new method in the main frame, and in the method index
+  function mainHashChanged(e) {
+    const id = e.newURL.split('#')[1];
+    highlightElement(id);
+    setCurrentMethod(window.parent.location.pathname);
   }
 
   // highlight the passed id in the main frame
   function highlightElement(id) {
-    const doc = top.mainFrame.document;
+    const doc = window.parent.document;
     for (const h of doc.querySelectorAll('.highlighted'))
       h.classList.remove('highlighted');
+    if (id === 'header')
+      return;
     const e = doc.getElementById(id);
     if (e)
       e.classList.add('highlighted');
   }
 
-  function setupHighlighting () {
-    for (const a of methodIndex.list.querySelectorAll('a[href*="#method-"]'))
-      a.addEventListener('click', highlightTarget);
-  }
+  // --- search boxes
 
-  // setup search boxes
   function setupSearches() {
     const helpText = 'filter...';
     setupSearch(classIndex.searchBox, classIndex.entries, helpText);
@@ -157,6 +294,13 @@ document.addEventListener('DOMContentLoaded', function () {
     searchBox.setAttribute('placeholder', helpText);
   }
 
+  // --- vertical manual resizing of the indexes
+  // div#file-index
+  // div#file-class-resizer  (absent if the above div is not there)
+  // div#class-index
+  // div#class-method-resizer
+  // div#method-index
+
   let startY;             // where drag begins
   let startTopIndex;      // index object above when drag begins
   let startBottomIndex;   // index object below when drag begins
@@ -164,7 +308,7 @@ document.addEventListener('DOMContentLoaded', function () {
   let startBottomHeight;  // height of the index below when drag begins
 
   function startDrag(e, topIndex, bottomIndex) {
-    startY = e.clientY;  // FIXME: probably int
+    startY = e.clientY;
     startTopIndex = topIndex;
     startBottomIndex = bottomIndex;
     startTopHeight = topIndex.currentHeight;
@@ -189,6 +333,7 @@ document.addEventListener('DOMContentLoaded', function () {
     placeResizers();
   }
 
+  // place the vertical resizers between their indexes
   function placeResizers() {
     if (fileClassResizer)
       fileClassResizer.style.top = `${fileIndex.currentHeight}px`;
@@ -196,13 +341,14 @@ document.addEventListener('DOMContentLoaded', function () {
       classMethodResizer.style.top = `${fileIndex.currentHeight + classIndex.currentHeight}px`;
   }
 
-  // setup callbacks resizing vertically & horizontally;
+  // --- resizing of the window by the user or by the left/main resizer in the main frame
+
   function setupResizing() {
-    // callback on resize event
     window.addEventListener('resize', function(e) { frameResized(false) });
   }
 
   // resize the left index blocks
+  // if initial is true, this is the first resize, called above when loading
   function frameResized(initial) {
 
     resizeSearchField(classIndex);
@@ -222,7 +368,7 @@ document.addEventListener('DOMContentLoaded', function () {
     const box = indexBlock.searchBox;
     const text = indexBlock.text;
 
-    const frameWidth = top.indexFrame.visualViewport.width;
+    const frameWidth = window.visualViewport.width;
 
     const textRect = text.getBoundingClientRect();
     const textWidth = textRect.width;
@@ -250,6 +396,11 @@ document.addEventListener('DOMContentLoaded', function () {
   }
 
   // returns the initial heights of index blocks for the current window size
+  // if the combined height of the 3 indexes is more than the window height:
+  // - shrinks the file index to 5 entries if more
+  // - shrinks the method index to 33%, but leaving at least 5 entries visible
+  // - shrinks the class index to the available space, but leaving at least 5 entries visible
+  // so if very little height, the result may not fit
   function initialHeights() {
 
     // returned information
@@ -316,6 +467,7 @@ document.addEventListener('DOMContentLoaded', function () {
   }
 
   // returns the updated heights of index blocks for the current window size
+  // resizes each index proportionally
   function updatedHeights() {
 
     let frameHeight = window.visualViewport.height;
@@ -354,7 +506,6 @@ document.addEventListener('DOMContentLoaded', function () {
       heights.methods = frameHeight - heights.files - heights.classes;
 
     return heights;
-
   }
 
 });

data/lib/rdoc/generator/ruby-lang/scripts/mainFrame.js

@@ -1,29 +1,188 @@
 /*
- * Script for the main frame.
- * An adaptation of (darkfish.js by Michael Granger)
- */
+  Script for the main frame.
+  Originally an adaptation of (darkfish.js by Michael Granger)
+*/
 
 document.addEventListener('DOMContentLoaded', function () {
 
+  const leftContainer = document.getElementById('left-container');
+  const leftFrame = document.getElementById('left-frame');
+  const resizer = document.getElementById('resizer');
+
+  setupTOC();
   setupShowSource();
   setupShowConstantValue();
   setupShowAllFiles();
   setupInnerLinksHighlight();
   highlightUrlHash();
 
-  // <div id="method-c-_httpdate" class="method-detail">
-  //   <div class="method-heading">
-  //     ...
-  //   </div>
-  //   <div class="method-description">
-  //     ...
-  //   <pre class="method-source-code">
-  //     (code)
-  //   </pre>
+  // --- resizing of the left frame
+
+  resizer.addEventListener('mousedown', startWidthResize);
+
+  let startX;       // where drag begins
+  let startWidth;   // width of left frame when drag begins
+  function startWidthResize(e) {
+    startX = e.clientX;
+    startWidth = leftContainer.getBoundingClientRect().width;
+    document.documentElement.addEventListener('mousemove', doWidthResize);
+    document.documentElement.addEventListener('mouseup', stopWidthResize);
+    leftFrame.contentDocument.addEventListener('mousemove', doWidthResize);
+    leftFrame.contentDocument.addEventListener('mouseup', stopWidthResize);
+  }
+
+  function stopWidthResize(e) {
+    document.documentElement.removeEventListener('mousemove', doWidthResize);
+    document.documentElement.removeEventListener('mouseup', stopWidthResize);
+    leftFrame.contentDocument.removeEventListener('mousemove', doWidthResize);
+    leftFrame.contentDocument.removeEventListener('mouseup', stopWidthResize);
+  }
+
+  function doWidthResize(e) {
+    const dX = e.clientX - startX;
+    const newWidth = startWidth + dX;
+    if (newWidth > 100)
+      leftContainer.style.width = `${newWidth}px`;
+  }
+
+  // --- TOC button setup
+
+  function setupTOC() {
+
+    const nav = document.createElement('nav');
+    nav.innerHTML = `
+      <button id="menu-button">
+        <img class="icon-hamburger">
+        <img class="icon-cross">
+      </button>
+      <div id="menu-content" class="hidden">
+        <p id="menu-top">
+          <a href="#header">(top)</a>
+        </p>
+        <div id="toc-content">
+        </div>
+      </div>
+    `;
+    const main = document.getElementById('main-container');
+    const doc = document.getElementById('documentation');
+    main.insertBefore(nav, doc);
+
+    const menu_button = document.getElementById('menu-button');
+    const menu_content = document.getElementById('menu-content');
+    const toc_content = document.getElementById('toc-content');
+
+    function createTOC() {
+      const headings = document.body.querySelectorAll('h1, h2, h3, h4, h5, h6');
+      if (headings.length == 0)
+        return false;
+      let generated_id_index = 0;
+      const first_summary_heading = firstSummaryHeading();
+      // console.log(`${headings.length} headings`);
+      for (const h of headings) {
+        // console.log(`name = ${h.tagName} id=${h.id} text = ${h.innerText}`);
+        if (!h.id) {
+          generated_id_index++;
+          h.setAttribute('id', `toc-auto-id-${generated_id_index}`);
+        }
+        if (h === first_summary_heading) {
+          const sp = document.createElement('p');
+          toc_content.appendChild(sp);
+          sp.setAttribute('class', 'h2');
+          sp.textContent = 'Summary';
+        }
+        // <p class="toc2"><a href="#label-News">News</a></p>
+        const p = document.createElement('p');
+        toc_content.appendChild(p);
+        p.setAttribute('class', h.tagName.toLowerCase());
+        const a = document.createElement('a');
+        p.appendChild(a);
+        a.setAttribute('href', `#${h.id}`);
+        a.textContent = h.innerText; // h.textContent;
+      }
+
+      return true;
+    }
+
+    function firstSummaryHeading() {
+      const ids = [
+        'class-aliases',
+        'method-list',
+        'namespace-list',
+        'include-list',
+        'constant-list',
+        'external-aliases',
+        'class-attributes',
+        'instance-attributes',
+      ];
+      for (const id of ids) {
+        const h = document.querySelector(`#${id} h3`);
+        if (h) return h;
+      }
+      return null;
+    }
+
+    if (!createTOC())
+      nav.classList.add('hidden');
+
+    // show/hide the menu/toc
+    menu_button.addEventListener('click', function(e) {
+      e.preventDefault();
+      toggleMenu();
+    });
+
+    // hide the menu on Escape
+    document.addEventListener('keydown', function(e) {
+      if (!isMenuVisible()) return;
+      if (e.code == 'Escape' && !e.ctrlKey) {
+        e.preventDefault();
+        hideMenu();
+      }
+    });
+
+    // hide the menu when clicking outside of nav
+    document.addEventListener('click', function (event) {
+      if (!isMenuVisible()) return;
+      if (!nav.contains(event.target))
+        hideMenu();
+    });
+
+    function hideMenu() {
+      menu_content.classList.add('hidden');
+      menu_button.classList.remove('show-close');
+    }
+
+    function showMenu() {
+      menu_content.classList.remove('hidden');
+      menu_button.classList.add('show-close');
+    }
+
+    function isMenuVisible() {
+      return !menu_content.classList.contains('hidden');
+    }
+
+    function toggleMenu() {
+      if (isMenuVisible())
+        hideMenu();
+      else
+        showMenu();
+    }
+
+  }
+
+  // --- toggle method source display
 
   function setupShowSource() {
     for (const node of document.querySelectorAll('.method-heading'))
       node.addEventListener('click', toggleSource);
+    // <div id="method-c-_httpdate" class="method-detail">
+    //   <div class="method-heading">
+    //     ...
+    //   </div>
+    //   <div class="method-description">
+    //     ...
+    //   <pre class="method-source-code">
+    //     (code)
+    //   </pre>
   }
 
   function toggleSource(e) {
@@ -33,22 +192,23 @@ document.addEventListener('DOMContentLoaded', function () {
       slideToggle(source);
   }
 
-  // <tr id="MONTHNAMES" class="const-display">
-  //   <td class="const-name"><p>MONTHNAMES</p></td>
-  //   <td class="const-desc">
-  //     <p>An array of strings of full month names in <a href="English.html"><code>English</code></a>.  The first element is nil.</p>
-  //   </td>
-  // <td><p class="click-advice">click to toggle value</p></td>
-  // </tr>
-  // <tr class="const-value">
-  //   <td></td>
-  //   <td><pre>mk_ary_of_str(13, monthnames)</pre></td>
-  //   <td></td>
-  // </tr>
+  // --- toggle constant value display
 
   function setupShowConstantValue() {
     for (const node of document.querySelectorAll('#constant-list .const-display'))
       node.addEventListener('click', toggleValue);
+    // <tr id="MONTHNAMES" class="const-display">
+    //   <td class="const-name"><p>MONTHNAMES</p></td>
+    //   <td class="const-desc">
+    //     <p>An array of strings of full month names in <a href="English.html"><code>English</code></a>.  The first element is nil.</p>
+    //   </td>
+    // <td><p class="click-advice">click to toggle value</p></td>
+    // </tr>
+    // <tr class="const-value">
+    //   <td></td>
+    //   <td><pre>mk_ary_of_str(13, monthnames)</pre></td>
+    //   <td></td>
+    // </tr>
   }
 
   function toggleValue(e) {
@@ -56,13 +216,15 @@ document.addEventListener('DOMContentLoaded', function () {
     toggleDisplay(e.currentTarget.nextElementSibling, 'table-row');
   }
 
-  function toggleDisplay(element, visible) {
-    if (element.style.display !== visible)
-      element.style.display = visible;
+  function toggleDisplay(element, visibleDisplayValue) {
+    if (element.style.display !== visibleDisplayValue)
+      element.style.display = visibleDisplayValue;
     else
       element.style.display = 'none';
   }
 
+  // --- toggle the display of all files where the class/module if defined
+
   function setupShowAllFiles() {
     const allFiles = document.getElementById('all-files');
     if (!allFiles) return;
@@ -80,11 +242,7 @@ document.addEventListener('DOMContentLoaded', function () {
     });
   }
 
-  function highlightUrlHash() {
-    const h = window.location.hash;
-    if (h && h.length > 1)
-      highlightElement(h.substring(1));
-  }
+  // --- highlight the target method when clicked from an inner method link
 
   function setupInnerLinksHighlight() {
     for (const a of document.querySelectorAll('a[href*="#"]'))
@@ -93,7 +251,7 @@ document.addEventListener('DOMContentLoaded', function () {
 
   function highlightTarget(e) {
     const href = e.currentTarget.getAttribute('href');
-    const match =/#(.*)/.exec(href);
+    const match = /#(.*)/.exec(href);
     if (match && match[1].length > 1)
       highlightElement(match[1]);
   }
@@ -101,11 +259,22 @@ document.addEventListener('DOMContentLoaded', function () {
   function highlightElement(id) {
     for (const h of document.querySelectorAll('.highlighted'))
       h.classList.remove('highlighted');
+    if (id === 'header')
+      return;
     const e = document.getElementById(id);
     if (e)
       e.classList.add('highlighted');
   }
 
+  // --- highlight the method if present in the location hash
+
+  function highlightUrlHash() {
+    const h = window.location.hash;
+    if (h && h.length > 1)
+      highlightElement(h.substring(1));
+  }
+
+  // --- smooth toggling (for source code)
   // from plain JS slideToggle https://github.com/ericbutler555/plain-js-slidetoggle
 
   function slideToggle(element, duration) {

data/lib/rdoc/generator/ruby-lang/scripts/quicksearch.js

@@ -7,26 +7,31 @@
     https://github.com/riklomas/quicksearch
 */
 
+// setup quick search:
+// - input: the text search box
+// - paragraphs: the paragraphs to show/hide
 function setupQuickSearch(input, paragraphs) {
 
-  let timeoutId;
-  const textCache = [];
-  const delay = 100;
-
-  // console.log(`setupQuickSearch(${input}, ${paragraphs.length} paragraphs)`)
+  let timeoutId;        // setTimeout id on key up
+  const delay = 100;    // delay for search after key up
+  const textCache = []; // cache of search texts (lowercase)
 
+  // fill the cache
   for (const node of paragraphs)
-    textCache.push(node.textContent.toLowerCase().trim());
+    textCache.push(node.querySelector('a').textContent.toLowerCase().trim());
 
+  // filter with the current content of the input box
   filter();
 
   input.addEventListener('keyup', trigger);
 
+  // calls filter() after the delay
   function trigger() {
     window.clearTimeout(timeoutId);
     timeoutId = window.setTimeout(filter, delay);
   }
 
+  // perform filtering
   function filter() {
 
     if (!input.value) {
@@ -43,6 +48,7 @@ function setupQuickSearch(input, paragraphs) {
         paragraphs[i].style.display = 'none';
   }
 
+  // does text contain all words?
   function containsAll(text, words) {
     for (const word of words)
       if (text.indexOf(word) === -1)