docyard 0.4.0 → 0.5.0

data/lib/docyard/templates/assets/js/components/table-of-contents.js

@@ -0,0 +1,301 @@
+/**
+ * TableOfContentsManager handles TOC interactions and scroll tracking
+ * Features: scroll spy, active highlighting, smooth scrolling, mobile toggle
+ */
+class TableOfContentsManager {
+  constructor() {
+    this.toc = document.querySelector('.docyard-toc');
+    if (!this.toc) return;
+
+    this.links = Array.from(this.toc.querySelectorAll('.docyard-toc__link'));
+    this.headings = this.getHeadings();
+    this.nav = this.toc.querySelector('.docyard-toc__nav');
+    this.activeLink = null;
+    this.observer = null;
+    this.ticking = false;
+
+    this.init();
+  }
+
+  init() {
+    if (this.headings.length === 0) return;
+
+    this.setupScrollSpy();
+    this.setupSmoothScrolling();
+    this.setupMobileToggle();
+    this.setupKeyboardNavigation();
+    this.handleInitialHash();
+  }
+
+  /**
+   * Check if viewport is mobile/tablet (TOC in secondary header)
+   * @returns {boolean}
+   */
+  isMobile() {
+    return window.innerWidth <= 1280;
+  }
+
+  /**
+   * Check if viewport is tablet (both headers visible)
+   * @returns {boolean}
+   */
+  isTablet() {
+    return window.innerWidth > 1024 && window.innerWidth <= 1280;
+  }
+
+  /**
+   * Get scroll offset based on viewport and header state
+   * @returns {number}
+   */
+  getScrollOffset() {
+    if (this.isTablet()) {
+      return 128;
+    }
+
+    if (window.innerWidth <= 1024) {
+      const header = document.querySelector('.header');
+      const isHeaderHidden = header && header.classList.contains('hide-on-scroll');
+      return isHeaderHidden ? 128 : 64;
+    }
+
+    return 100;
+  }
+
+  /**
+   * Get all headings referenced in TOC
+   * @returns {Array<HTMLElement>}
+   */
+  getHeadings() {
+    return this.links
+      .map(link => {
+        const id = link.dataset.headingId;
+        return document.getElementById(id);
+      })
+      .filter(Boolean);
+  }
+
+  /**
+   * Setup Intersection Observer for scroll spy
+   */
+  setupScrollSpy() {
+    const options = {
+      root: null,
+      rootMargin: '-80px 0px -80% 0px',
+      threshold: 0
+    };
+
+    this.observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          this.setActiveLink(entry.target.id);
+        }
+      });
+    }, options);
+
+    this.headings.forEach(heading => {
+      this.observer.observe(heading);
+    });
+  }
+
+  /**
+   * Set active link in TOC
+   * @param {string} id - Heading ID
+   */
+  setActiveLink(id) {
+    const link = this.links.find(l => l.dataset.headingId === id);
+    if (!link || link === this.activeLink) return;
+
+    if (this.activeLink) {
+      this.activeLink.classList.remove('is-active');
+    }
+
+    link.classList.add('is-active');
+    this.activeLink = link;
+
+    this.scrollLinkIntoView(link);
+  }
+
+  /**
+   * Scroll TOC to keep active link visible
+   * @param {HTMLElement} link - Active link element
+   */
+  scrollLinkIntoView(link) {
+    if (this.isMobile()) return;
+
+    if (!this.ticking) {
+      requestAnimationFrame(() => {
+        const tocRect = this.toc.getBoundingClientRect();
+        const linkRect = link.getBoundingClientRect();
+
+        if (linkRect.top < tocRect.top || linkRect.bottom > tocRect.bottom) {
+          link.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+        }
+
+        this.ticking = false;
+      });
+      this.ticking = true;
+    }
+  }
+
+  /**
+   * Setup smooth scrolling for TOC links
+   */
+  setupSmoothScrolling() {
+    this.links.forEach(link => {
+      link.addEventListener('click', (e) => {
+        e.preventDefault();
+
+        const id = link.dataset.headingId;
+        const heading = document.getElementById(id);
+
+        if (heading) {
+          const offsetTop = heading.getBoundingClientRect().top + window.pageYOffset - this.getScrollOffset();
+
+          window.scrollTo({
+            top: offsetTop,
+            behavior: 'smooth'
+          });
+
+          history.pushState(null, null, `#${id}`);
+
+          heading.focus({ preventScroll: true });
+
+          // Close mobile menu after clicking a link
+          if (this.isMobile()) {
+            this.collapseMobile();
+          }
+        }
+      });
+    });
+  }
+
+  /**
+   * Setup mobile toggle functionality
+   */
+  setupMobileToggle() {
+    const secondaryToggle = document.querySelector('.secondary-header-toc-toggle');
+
+    if (!secondaryToggle || !this.nav) {
+      return;
+    }
+
+    secondaryToggle.addEventListener('click', () => {
+      const isExpanded = secondaryToggle.getAttribute('aria-expanded') === 'true';
+      secondaryToggle.setAttribute('aria-expanded', !isExpanded);
+      this.nav.classList.toggle('is-expanded', !isExpanded);
+
+      if (!isExpanded) {
+        document.body.style.overflow = 'hidden';
+      } else {
+        document.body.style.overflow = '';
+      }
+    });
+
+    // Close menu when clicking outside (mobile only)
+    document.addEventListener('click', (e) => {
+      if (!this.isMobile()) return;
+
+      const isExpanded = secondaryToggle.getAttribute('aria-expanded') === 'true';
+      if (!isExpanded) return;
+
+      const isClickInsideToc = this.nav.contains(e.target);
+      const isClickOnToggle = secondaryToggle.contains(e.target);
+
+      if (!isClickInsideToc && !isClickOnToggle) {
+        this.collapseMobile();
+      }
+    });
+  }
+
+  /**
+   * Collapse mobile TOC
+   */
+  collapseMobile() {
+    const secondaryToggle = document.querySelector('.secondary-header-toc-toggle');
+    if (secondaryToggle) {
+      secondaryToggle.setAttribute('aria-expanded', 'false');
+      if (this.nav) {
+        this.nav.classList.remove('is-expanded');
+      }
+      document.body.style.overflow = '';
+    }
+  }
+
+  /**
+   * Setup keyboard navigation
+   */
+  setupKeyboardNavigation() {
+    this.links.forEach((link, index) => {
+      link.addEventListener('keydown', (e) => {
+        let targetIndex = -1;
+
+        switch (e.key) {
+          case 'ArrowDown':
+            e.preventDefault();
+            targetIndex = index + 1;
+            break;
+          case 'ArrowUp':
+            e.preventDefault();
+            targetIndex = index - 1;
+            break;
+          case 'Home':
+            e.preventDefault();
+            targetIndex = 0;
+            break;
+          case 'End':
+            e.preventDefault();
+            targetIndex = this.links.length - 1;
+            break;
+          default:
+            return;
+        }
+
+        if (targetIndex >= 0 && targetIndex < this.links.length) {
+          this.links[targetIndex].focus();
+        }
+      });
+    });
+  }
+
+  /**
+   * Handle initial hash in URL on page load
+   */
+  handleInitialHash() {
+    const hash = window.location.hash.slice(1);
+    if (!hash) return;
+
+    const heading = document.getElementById(hash);
+    if (!heading) return;
+
+    setTimeout(() => {
+      this.setActiveLink(hash);
+
+      const offsetTop = heading.getBoundingClientRect().top + window.pageYOffset - this.getScrollOffset();
+      window.scrollTo({
+        top: offsetTop,
+        behavior: 'auto'
+      });
+    }, 100);
+  }
+
+  /**
+   * Cleanup and destroy
+   */
+  destroy() {
+    if (this.observer) {
+      this.observer.disconnect();
+    }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  document.addEventListener('DOMContentLoaded', () => {
+    window.tocManager = new TableOfContentsManager();
+  });
+
+  window.addEventListener('beforeunload', () => {
+    if (window.tocManager) {
+      window.tocManager.destroy();
+    }
+  });
+}

data/lib/docyard/templates/layouts/default.html.erb

@@ -51,10 +51,12 @@
   <div class="secondary-header">
     <button class="secondary-header-menu" aria-label="Toggle navigation menu" aria-expanded="false">
       <svg class="icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="18" height="18">
-        <path d="M32,64a8,8,0,0,1,8-8H216a8,8,0,0,1,0,16H40A8,8,0,0,1,32,64Zm8,48H168a8,8,0,0,0,0-16H40a8,8,0,0,0,0,16Zm176,24H40a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Zm-48,40H40a8,8,0,0,0,0,16H168a8,8,0,0,0,0-16Z"></path>
+        <path d="M224,128a8,8,0,0,1-8,8H40a8,8,0,0,1,0-16H216A8,8,0,0,1,224,128ZM40,72H216a8,8,0,0,0,0-16H40a8,8,0,0,0,0,16ZM216,184H40a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Z"></path>
       </svg>
       <span>Menu</span>
     </button>
+
+    <%= render_partial('_table_of_contents_toggle') %>
   </div>
 
   <!-- Mobile overlay -->
@@ -68,8 +70,14 @@
     <div class="layout-main">
       <main id="main-content" class="content">
         <%= @content %>
+
+        <!-- Previous/Next Navigation -->
+        <%= @prev_next_html %>
       </main>
     </div>
+
+    <!-- Table of contents -->
+    <%= render_partial('_table_of_contents') %>
   </div>
 
   <script src="/assets/js/theme.js"></script>

data/lib/docyard/templates/partials/_heading_anchor.html.erb

@@ -0,0 +1 @@
+<a href="#<%= @id %>" class="heading-anchor" aria-label="Link to this section" data-heading-id="<%= @id %>">#</a>

data/lib/docyard/templates/partials/_prev_next.html.erb

@@ -0,0 +1,23 @@
+<% if @prev || @next %>
+<footer class="doc-footer">
+  <nav class="pager" aria-labelledby="doc-footer-aria-label">
+    <span id="doc-footer-aria-label" class="visually-hidden">Pager</span>
+
+    <% if @prev %>
+    <a href="<%= link_path(@prev[:path]) %>" class="pager-link prev" title="<%= @prev[:title] %>">
+      <span class="pager-label"><%= @prev_text %></span>
+      <span class="pager-title"><%= @prev[:title] %></span>
+    </a>
+    <% else %>
+    <span></span>
+    <% end %>
+
+    <% if @next %>
+    <a href="<%= link_path(@next[:path]) %>" class="pager-link next" title="<%= @next[:title] %>">
+      <span class="pager-label"><%= @next_text %></span>
+      <span class="pager-title"><%= @next[:title] %></span>
+    </a>
+    <% end %>
+  </nav>
+</footer>
+<% end %>

data/lib/docyard/templates/partials/_table_of_contents.html.erb

@@ -0,0 +1,45 @@
+<% unless @toc.empty? %>
+  <aside class="docyard-toc" aria-label="Table of contents">
+    <div class="docyard-toc__header">
+      <h2 class="docyard-toc__title">
+        <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 256 256" aria-hidden="true">
+          <path d="M88,64a8,8,0,0,1,8-8H216a8,8,0,0,1,0,16H96A8,8,0,0,1,88,64Zm128,56H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Zm0,64H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16ZM56,56H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Z"/>
+        </svg>
+        On this page
+      </h2>
+    </div>
+    <nav id="toc-content" class="docyard-toc__nav">
+      <ul class="docyard-toc__list">
+        <% @toc.each do |heading| %>
+          <li class="docyard-toc__item docyard-toc__item--level-<%= heading[:level] %>">
+            <a href="#<%= heading[:id] %>" class="docyard-toc__link" data-heading-id="<%= heading[:id] %>" title="<%= heading[:text] %>">
+              <%= heading[:text] %>
+            </a>
+            <% unless heading[:children].empty? %>
+              <ul class="docyard-toc__list">
+                <% heading[:children].each do |child| %>
+                  <li class="docyard-toc__item docyard-toc__item--level-<%= child[:level] %>">
+                    <a href="#<%= child[:id] %>" class="docyard-toc__link" data-heading-id="<%= child[:id] %>" title="<%= child[:text] %>">
+                      <%= child[:text] %>
+                    </a>
+                    <% unless child[:children].empty? %>
+                      <ul class="docyard-toc__list">
+                        <% child[:children].each do |grandchild| %>
+                          <li class="docyard-toc__item docyard-toc__item--level-<%= grandchild[:level] %>">
+                            <a href="#<%= grandchild[:id] %>" class="docyard-toc__link" data-heading-id="<%= grandchild[:id] %>" title="<%= grandchild[:text] %>">
+                              <%= grandchild[:text] %>
+                            </a>
+                          </li>
+                        <% end %>
+                      </ul>
+                    <% end %>
+                  </li>
+                <% end %>
+              </ul>
+            <% end %>
+          </li>
+        <% end %>
+      </ul>
+    </nav>
+  </aside>
+<% end %>

data/lib/docyard/templates/partials/_table_of_contents_toggle.html.erb

@@ -0,0 +1,8 @@
+<% unless @toc.empty? %>
+  <button class="secondary-header-toc-toggle" aria-expanded="false" aria-controls="toc-content" aria-label="Toggle table of contents">
+    <span>On this page</span>
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true">
+      <path d="M213.66,101.66l-80,80a8,8,0,0,1-11.32,0l-80-80A8,8,0,0,1,53.66,90.34L128,164.69l74.34-74.35a8,8,0,0,1,11.32,11.32Z"/>
+    </svg>
+  </button>
+<% end %>

data/lib/docyard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docyard
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docyard
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sanif Himani
@@ -194,9 +194,11 @@ files:
 - lib/docyard/components/callout_processor.rb
 - lib/docyard/components/code_block_processor.rb
 - lib/docyard/components/code_detector.rb
+- lib/docyard/components/heading_anchor_processor.rb
 - lib/docyard/components/icon_detector.rb
 - lib/docyard/components/icon_processor.rb
 - lib/docyard/components/registry.rb
+- lib/docyard/components/table_of_contents_processor.rb
 - lib/docyard/components/table_wrapper_processor.rb
 - lib/docyard/components/tabs_parser.rb
 - lib/docyard/components/tabs_processor.rb
@@ -213,6 +215,7 @@ files:
 - lib/docyard/language_mapping.rb
 - lib/docyard/logging.rb
 - lib/docyard/markdown.rb
+- lib/docyard/prev_next_builder.rb
 - lib/docyard/preview_server.rb
 - lib/docyard/rack_application.rb
 - lib/docyard/renderer.rb
@@ -229,9 +232,12 @@ files:
 - lib/docyard/templates/assets/css/code.css
 - lib/docyard/templates/assets/css/components/callout.css
 - lib/docyard/templates/assets/css/components/code-block.css
+- lib/docyard/templates/assets/css/components/heading-anchor.css
 - lib/docyard/templates/assets/css/components/icon.css
 - lib/docyard/templates/assets/css/components/logo.css
 - lib/docyard/templates/assets/css/components/navigation.css
+- lib/docyard/templates/assets/css/components/prev-next.css
+- lib/docyard/templates/assets/css/components/table-of-contents.css
 - lib/docyard/templates/assets/css/components/tabs.css
 - lib/docyard/templates/assets/css/components/theme-toggle.css
 - lib/docyard/templates/assets/css/layout.css
@@ -242,7 +248,9 @@ files:
 - lib/docyard/templates/assets/css/variables.css
 - lib/docyard/templates/assets/favicon.svg
 - lib/docyard/templates/assets/js/components/code-block.js
+- lib/docyard/templates/assets/js/components/heading-anchor.js
 - lib/docyard/templates/assets/js/components/navigation.js
+- lib/docyard/templates/assets/js/components/table-of-contents.js
 - lib/docyard/templates/assets/js/components/tabs.js
 - lib/docyard/templates/assets/js/reload.js
 - lib/docyard/templates/assets/js/theme.js
@@ -258,6 +266,7 @@ files:
 - lib/docyard/templates/markdown/index.md.erb
 - lib/docyard/templates/partials/_callout.html.erb
 - lib/docyard/templates/partials/_code_block.html.erb
+- lib/docyard/templates/partials/_heading_anchor.html.erb
 - lib/docyard/templates/partials/_icon.html.erb
 - lib/docyard/templates/partials/_icon_file_extension.html.erb
 - lib/docyard/templates/partials/_nav_group.html.erb
@@ -265,8 +274,11 @@ files:
 - lib/docyard/templates/partials/_nav_leaf.html.erb
 - lib/docyard/templates/partials/_nav_list.html.erb
 - lib/docyard/templates/partials/_nav_section.html.erb
+- lib/docyard/templates/partials/_prev_next.html.erb
 - lib/docyard/templates/partials/_sidebar.html.erb
 - lib/docyard/templates/partials/_sidebar_footer.html.erb
+- lib/docyard/templates/partials/_table_of_contents.html.erb
+- lib/docyard/templates/partials/_table_of_contents_toggle.html.erb
 - lib/docyard/templates/partials/_tabs.html.erb
 - lib/docyard/templates/partials/_theme_toggle.html.erb
 - lib/docyard/utils/path_resolver.rb