docyard 0.3.0 → 0.5.0

data/lib/docyard/templates/assets/js/components/heading-anchor.js

@@ -0,0 +1,90 @@
+/**
+ * HeadingAnchorManager handles anchor link interactions
+ * Provides copy-to-clipboard functionality with visual feedback
+ */
+class HeadingAnchorManager {
+  constructor() {
+    this.anchors = document.querySelectorAll('.heading-anchor');
+    this.init();
+  }
+
+  init() {
+    this.anchors.forEach(anchor => {
+      anchor.addEventListener('click', (e) => this.handleClick(e, anchor));
+    });
+  }
+
+  /**
+   * Handle anchor link click
+   * @param {Event} e - Click event
+   * @param {HTMLElement} anchor - Anchor element
+   */
+  handleClick(e, anchor) {
+    e.preventDefault();
+
+    const headingId = anchor.dataset.headingId;
+    const url = `${window.location.origin}${window.location.pathname}#${headingId}`;
+
+    this.copyToClipboard(url, anchor);
+
+    history.pushState(null, null, `#${headingId}`);
+
+    const heading = document.getElementById(headingId);
+    if (heading) {
+      heading.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }
+
+  /**
+   * Copy text to clipboard with visual feedback
+   * @param {string} text - Text to copy
+   * @param {HTMLElement} anchor - Anchor element for feedback
+   */
+  async copyToClipboard(text, anchor) {
+    try {
+      await navigator.clipboard.writeText(text);
+      this.showFeedback(anchor, true);
+    } catch (err) {
+      this.fallbackCopyToClipboard(text);
+      this.showFeedback(anchor, true);
+    }
+  }
+
+  /**
+   * Fallback copy method for older browsers
+   * @param {string} text - Text to copy
+   */
+  fallbackCopyToClipboard(text) {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    document.execCommand('copy');
+    document.body.removeChild(textarea);
+  }
+
+  /**
+   * Show visual feedback on copy
+   * @param {HTMLElement} anchor - Anchor element
+   * @param {boolean} success - Whether copy succeeded
+   */
+  showFeedback(anchor, success) {
+    const originalTitle = anchor.getAttribute('aria-label');
+    anchor.setAttribute('aria-label', success ? 'Link copied!' : 'Failed to copy');
+
+    anchor.style.color = success ? 'var(--color-success, #10b981)' : 'var(--color-danger, #ef4444)';
+
+    setTimeout(() => {
+      anchor.setAttribute('aria-label', originalTitle);
+      anchor.style.color = '';
+    }, 2000);
+  }
+}
+
+if (typeof window !== 'undefined') {
+  document.addEventListener('DOMContentLoaded', () => {
+    new HeadingAnchorManager();
+  });
+}

data/lib/docyard/templates/assets/js/components/navigation.js

@@ -0,0 +1,225 @@
+// Docyard Navigation JavaScript
+// Handles sidebar navigation, mobile menu, accordion groups, and scroll behavior
+
+(function() {
+  'use strict';
+
+  function initMobileMenu() {
+    const toggle = document.querySelector('.secondary-header-menu');
+    const sidebar = document.querySelector('.sidebar');
+    const overlay = document.querySelector('.mobile-overlay');
+
+    if (!toggle || !sidebar || !overlay) {
+      return;
+    }
+
+    function openMenu() {
+      sidebar.classList.add('is-open');
+      overlay.classList.add('is-visible');
+      toggle.setAttribute('aria-expanded', 'true');
+      document.body.style.overflow = 'hidden';
+    }
+
+    function closeMenu() {
+      sidebar.classList.remove('is-open');
+      overlay.classList.remove('is-visible');
+      toggle.setAttribute('aria-expanded', 'false');
+      document.body.style.overflow = '';
+    }
+
+    function toggleMenu() {
+      if (sidebar.classList.contains('is-open')) {
+        closeMenu();
+      } else {
+        openMenu();
+      }
+    }
+
+    toggle.addEventListener('click', function(e) {
+      toggleMenu();
+    });
+    overlay.addEventListener('click', closeMenu);
+
+    document.addEventListener('keydown', function(e) {
+      if (e.key === 'Escape' && sidebar.classList.contains('is-open')) {
+        closeMenu();
+      }
+    });
+
+    sidebar.querySelectorAll('a').forEach(function(link) {
+      link.addEventListener('click', closeMenu);
+    });
+  }
+
+  function initAccordion() {
+    const toggles = document.querySelectorAll('.nav-group-toggle');
+
+    toggles.forEach(function(toggle) {
+      toggle.addEventListener('click', function() {
+        const expanded = toggle.getAttribute('aria-expanded') === 'true';
+        const children = toggle.nextElementSibling;
+
+        if (!children || !children.classList.contains('nav-group-children')) {
+          return;
+        }
+
+        toggle.setAttribute('aria-expanded', !expanded);
+        children.classList.toggle('collapsed');
+
+        if (expanded) {
+          children.style.maxHeight = '0';
+        } else {
+          children.style.maxHeight = children.scrollHeight + 'px';
+        }
+      });
+    });
+
+    document.querySelectorAll('.nav-group-children.collapsed').forEach(function(el) {
+      el.style.maxHeight = '0';
+    });
+  }
+
+  function expandActiveGroups() {
+    const activeLinks = document.querySelectorAll('a.active');
+
+    activeLinks.forEach(function(activeLink) {
+      let parent = activeLink.closest('.nav-group-children');
+
+      while (parent) {
+        if (parent.classList.contains('nav-group-children')) {
+          parent.classList.remove('collapsed');
+
+          const toggle = parent.previousElementSibling;
+          if (toggle && toggle.classList.contains('nav-group-toggle')) {
+            toggle.setAttribute('aria-expanded', 'true');
+
+            parent.style.maxHeight = 'none';
+            const height = parent.scrollHeight;
+            parent.style.maxHeight = height + 'px';
+          }
+        }
+
+        parent = parent.parentElement?.closest('.nav-group-children');
+      }
+    });
+  }
+
+  function initSidebarScroll() {
+    const scrollContainer = document.querySelector('.sidebar nav');
+    if (!scrollContainer) return;
+
+    const STORAGE_KEY = 'docyard_sidebar_scroll';
+    const savedPosition = sessionStorage.getItem(STORAGE_KEY);
+
+    if (savedPosition) {
+      const position = parseInt(savedPosition, 10);
+      scrollContainer.scrollTop = position;
+
+      setTimeout(function() {
+        scrollContainer.scrollTop = position;
+      }, 100);
+    } else {
+      const activeLink = scrollContainer.querySelector('a.active');
+      if (activeLink) {
+        setTimeout(function() {
+          activeLink.scrollIntoView({
+            behavior: 'instant',
+            block: 'center'
+          });
+        }, 50);
+      }
+    }
+
+    scrollContainer.querySelectorAll('a').forEach(function(link) {
+      link.addEventListener('click', function() {
+        sessionStorage.setItem(STORAGE_KEY, scrollContainer.scrollTop);
+      });
+    });
+
+    let scrollTimeout;
+    scrollContainer.addEventListener('scroll', function() {
+      clearTimeout(scrollTimeout);
+      scrollTimeout = setTimeout(function() {
+        sessionStorage.setItem(STORAGE_KEY, scrollContainer.scrollTop);
+      }, 150);
+    });
+
+    const logo = document.querySelector('.header-logo');
+    if (logo) {
+      logo.addEventListener('click', function() {
+        sessionStorage.removeItem(STORAGE_KEY);
+        scrollContainer.scrollTop = 0;
+      });
+    }
+  }
+
+  function initScrollBehavior() {
+    const header = document.querySelector('.header');
+    const secondaryHeader = document.querySelector('.secondary-header');
+
+    if (!header || !secondaryHeader) return;
+
+    let lastScrollTop = 0;
+    let ticking = false;
+
+    function isMobile() {
+      return window.innerWidth <= 1024;
+    }
+
+    function updateHeaders() {
+      if (!isMobile()) {
+        header.classList.remove('hide-on-scroll');
+        secondaryHeader.classList.remove('shift-up');
+        ticking = false;
+        return;
+      }
+
+      const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+
+      if (scrollTop > lastScrollTop && scrollTop > 100) {
+        header.classList.add('hide-on-scroll');
+        secondaryHeader.classList.add('shift-up');
+      } else if (scrollTop < lastScrollTop) {
+        header.classList.remove('hide-on-scroll');
+        secondaryHeader.classList.remove('shift-up');
+      }
+
+      lastScrollTop = scrollTop <= 0 ? 0 : scrollTop;
+      ticking = false;
+    }
+
+    window.addEventListener('scroll', function() {
+      if (!ticking) {
+        window.requestAnimationFrame(updateHeaders);
+        ticking = true;
+      }
+    });
+
+    window.addEventListener('resize', function() {
+      if (!isMobile()) {
+        header.classList.remove('hide-on-scroll');
+        secondaryHeader.classList.remove('shift-up');
+      }
+    });
+  }
+
+  if ('scrollRestoration' in history) {
+    history.scrollRestoration = 'manual';
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() {
+      initMobileMenu();
+      initAccordion();
+      expandActiveGroups();
+      initSidebarScroll();
+      initScrollBehavior();
+    });
+  } else {
+    initMobileMenu();
+    initAccordion();
+    expandActiveGroups();
+    initSidebarScroll();
+    initScrollBehavior();
+  }
+})();

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();
+    }
+  });
+}