jekyll-theme-zer0 0.16.0 → 0.17.2

data/assets/js/modules/navigation/sidebar-state.js

@@ -0,0 +1,267 @@
+/**
+ * ===================================================================
+ * SIDEBAR STATE - Persistence and State Management
+ * ===================================================================
+ * 
+ * File: sidebar-state.js
+ * Path: assets/js/modules/navigation/sidebar-state.js
+ * Purpose: Manage and persist navigation state across page loads
+ * 
+ * Features:
+ * - Persist expanded/collapsed state of tree nodes in localStorage
+ * - Emit custom events for state changes
+ * - Restore state on page load
+ * - Track sidebar open/close state
+ * 
+ * Usage:
+ *   import { SidebarState } from './sidebar-state.js';
+ *   const state = new SidebarState();
+ *   state.setExpanded('docs-section', true);
+ * 
+ * ===================================================================
+ */
+
+import { config } from './config.js';
+
+export class SidebarState {
+    constructor() {
+        this._storagePrefix = config.state.storagePrefix;
+        this._expandedNodes = new Set();
+        
+        this._init();
+    }
+
+    /**
+     * Initialize state management
+     * @private
+     */
+    _init() {
+        // Load persisted state
+        this._loadState();
+        
+        // Listen for collapse events from Bootstrap
+        this._setupCollapseListeners();
+        
+        // Restore expanded states on page load
+        this._restoreExpandedStates();
+
+        console.log('SidebarState: Initialized');
+    }
+
+    /**
+     * Load state from localStorage
+     * @private
+     */
+    _loadState() {
+        try {
+            const key = this._storagePrefix + config.state.keys.expandedNodes;
+            const stored = localStorage.getItem(key);
+            if (stored) {
+                const parsed = JSON.parse(stored);
+                this._expandedNodes = new Set(parsed);
+            }
+        } catch (error) {
+            console.warn('SidebarState: Could not load state from localStorage', error);
+        }
+    }
+
+    /**
+     * Save state to localStorage
+     * @private
+     */
+    _saveState() {
+        try {
+            const key = this._storagePrefix + config.state.keys.expandedNodes;
+            const value = JSON.stringify([...this._expandedNodes]);
+            localStorage.setItem(key, value);
+        } catch (error) {
+            console.warn('SidebarState: Could not save state to localStorage', error);
+        }
+    }
+
+    /**
+     * Setup listeners for Bootstrap collapse events
+     * @private
+     */
+    _setupCollapseListeners() {
+        // Listen for collapse show events
+        document.addEventListener('show.bs.collapse', (event) => {
+            const nodeId = event.target.id;
+            if (nodeId && this._isNavNode(event.target)) {
+                this.setExpanded(nodeId, true);
+            }
+        });
+
+        // Listen for collapse hide events
+        document.addEventListener('hide.bs.collapse', (event) => {
+            const nodeId = event.target.id;
+            if (nodeId && this._isNavNode(event.target)) {
+                this.setExpanded(nodeId, false);
+            }
+        });
+    }
+
+    /**
+     * Check if element is a navigation node
+     * @private
+     * @param {Element} element
+     * @returns {boolean}
+     */
+    _isNavNode(element) {
+        // Check if element is within sidebar or has nav-related classes
+        return element.closest('.bd-sidebar, .nav-tree, [data-nav-tree]') !== null;
+    }
+
+    /**
+     * Restore expanded states from persisted data
+     * @private
+     */
+    _restoreExpandedStates() {
+        // Wait for DOM to be ready
+        requestAnimationFrame(() => {
+            this._expandedNodes.forEach(nodeId => {
+                const element = document.getElementById(nodeId);
+                if (element && typeof bootstrap !== 'undefined') {
+                    // Show the collapse without animation
+                    element.classList.add('show');
+                    
+                    // Update the toggle button state
+                    const toggle = document.querySelector(`[data-bs-target="#${nodeId}"]`);
+                    if (toggle) {
+                        toggle.classList.remove('collapsed');
+                        toggle.setAttribute('aria-expanded', 'true');
+                    }
+                }
+            });
+        });
+    }
+
+    /**
+     * Set expanded state for a node
+     * @param {string} nodeId - The ID of the collapse element
+     * @param {boolean} expanded - Whether the node should be expanded
+     */
+    setExpanded(nodeId, expanded) {
+        if (expanded) {
+            this._expandedNodes.add(nodeId);
+        } else {
+            this._expandedNodes.delete(nodeId);
+        }
+        
+        this._saveState();
+        
+        // Dispatch custom event
+        document.dispatchEvent(new CustomEvent('navigation:toggle', {
+            detail: { 
+                nodeId: nodeId,
+                expanded: expanded
+            }
+        }));
+    }
+
+    /**
+     * Check if a node is expanded
+     * @param {string} nodeId
+     * @returns {boolean}
+     */
+    isExpanded(nodeId) {
+        return this._expandedNodes.has(nodeId);
+    }
+
+    /**
+     * Expand all nodes
+     */
+    expandAll() {
+        const collapses = document.querySelectorAll('.bd-sidebar .collapse, .nav-tree .collapse');
+        collapses.forEach(collapse => {
+            if (collapse.id) {
+                this._expandedNodes.add(collapse.id);
+                if (typeof bootstrap !== 'undefined') {
+                    const bsCollapse = bootstrap.Collapse.getOrCreateInstance(collapse, { toggle: false });
+                    bsCollapse.show();
+                }
+            }
+        });
+        this._saveState();
+        
+        document.dispatchEvent(new CustomEvent('navigation:expandAll'));
+    }
+
+    /**
+     * Collapse all nodes
+     */
+    collapseAll() {
+        const collapses = document.querySelectorAll('.bd-sidebar .collapse.show, .nav-tree .collapse.show');
+        collapses.forEach(collapse => {
+            if (collapse.id) {
+                this._expandedNodes.delete(collapse.id);
+                if (typeof bootstrap !== 'undefined') {
+                    const bsCollapse = bootstrap.Collapse.getInstance(collapse);
+                    if (bsCollapse) {
+                        bsCollapse.hide();
+                    }
+                }
+            }
+        });
+        this._saveState();
+        
+        document.dispatchEvent(new CustomEvent('navigation:collapseAll'));
+    }
+
+    /**
+     * Expand path to a specific element (expand all parents)
+     * @param {string} targetId - The ID of the target element to reveal
+     */
+    expandPathTo(targetId) {
+        const target = document.getElementById(targetId);
+        if (!target) return;
+
+        // Find all parent collapses
+        let parent = target.closest('.collapse');
+        while (parent) {
+            if (parent.id) {
+                this.setExpanded(parent.id, true);
+                if (typeof bootstrap !== 'undefined') {
+                    const bsCollapse = bootstrap.Collapse.getOrCreateInstance(parent, { toggle: false });
+                    bsCollapse.show();
+                }
+            }
+            parent = parent.parentElement?.closest('.collapse');
+        }
+    }
+
+    /**
+     * Get all expanded node IDs
+     * @returns {string[]}
+     */
+    getExpandedNodes() {
+        return [...this._expandedNodes];
+    }
+
+    /**
+     * Clear all persisted state
+     */
+    clearState() {
+        this._expandedNodes.clear();
+        
+        try {
+            Object.values(config.state.keys).forEach(key => {
+                localStorage.removeItem(this._storagePrefix + key);
+            });
+        } catch (error) {
+            console.warn('SidebarState: Could not clear localStorage', error);
+        }
+        
+        document.dispatchEvent(new CustomEvent('navigation:stateCleared'));
+    }
+
+    /**
+     * Cleanup
+     */
+    destroy() {
+        // State is persisted, nothing to clean up
+        console.log('SidebarState: Destroyed');
+    }
+}
+
+export default SidebarState;

data/assets/js/modules/navigation/smooth-scroll.js

@@ -0,0 +1,153 @@
+/**
+ * ===================================================================
+ * SMOOTH SCROLL - Enhanced Anchor Navigation
+ * ===================================================================
+ * 
+ * File: smooth-scroll.js
+ * Path: assets/js/modules/navigation/smooth-scroll.js
+ * Purpose: Smooth scrolling to anchor links with header offset
+ * 
+ * Features:
+ * - Smooth scroll with configurable offset for fixed headers
+ * - URL hash update without page jump
+ * - Closes mobile offcanvas after navigation
+ * - Accessibility-focused with proper focus management
+ * 
+ * Usage:
+ *   import { SmoothScroll } from './smooth-scroll.js';
+ *   const smoothScroll = new SmoothScroll();
+ * 
+ * ===================================================================
+ */
+
+import { config, isBelowBreakpoint } from './config.js';
+
+/**
+ * Get all elements safely
+ * @param {string} selector - CSS selector
+ * @returns {NodeList}
+ */
+function getElements(selector) {
+    try {
+        return document.querySelectorAll(selector);
+    } catch (error) {
+        console.warn(`SmoothScroll: Elements not found - ${selector}`);
+        return [];
+    }
+}
+
+export class SmoothScroll {
+    constructor() {
+        this.tocLinks = getElements(config.selectors.tocLinks);
+        this._init();
+    }
+
+    /**
+     * Initialize click handlers
+     * @private
+     */
+    _init() {
+        this.tocLinks.forEach(link => {
+            link.addEventListener('click', e => this._handleClick(e));
+        });
+        console.log(`SmoothScroll: Initialized with ${this.tocLinks.length} links`);
+    }
+
+    /**
+     * Handle click on TOC link
+     * @private
+     * @param {Event} event
+     */
+    _handleClick(event) {
+        const href = event.currentTarget.getAttribute('href');
+        
+        if (!href || !href.startsWith('#')) return;
+
+        event.preventDefault();
+        
+        const targetId = href.substring(1);
+        const targetElement = document.getElementById(targetId);
+
+        if (!targetElement) {
+            console.warn(`SmoothScroll: Target element #${targetId} not found`);
+            return;
+        }
+
+        // Scroll to target
+        this.scrollToElement(targetElement);
+
+        // Update URL without jumping
+        if (history.pushState) {
+            history.pushState(null, null, href);
+        }
+
+        // Close mobile offcanvas if open
+        this._closeMobileOffcanvas();
+
+        // Dispatch custom event
+        document.dispatchEvent(new CustomEvent('navigation:scroll', {
+            detail: { 
+                targetId: targetId,
+                targetElement: targetElement
+            }
+        }));
+    }
+
+    /**
+     * Scroll to an element with offset
+     * @param {Element} element - Target element
+     * @param {number} [offset] - Optional custom offset
+     */
+    scrollToElement(element, offset = config.smoothScroll.offset) {
+        const elementPosition = element.getBoundingClientRect().top;
+        const offsetPosition = elementPosition + window.pageYOffset - offset;
+
+        window.scrollTo({
+            top: offsetPosition,
+            behavior: config.smoothScroll.behavior
+        });
+
+        // Update focus for accessibility
+        element.setAttribute('tabindex', '-1');
+        element.focus({ preventScroll: true });
+    }
+
+    /**
+     * Scroll to element by ID
+     * @param {string} id - Element ID (without #)
+     * @param {number} [offset] - Optional custom offset
+     */
+    scrollToId(id, offset) {
+        const element = document.getElementById(id);
+        if (element) {
+            this.scrollToElement(element, offset);
+        }
+    }
+
+    /**
+     * Close mobile offcanvas if viewport is below lg breakpoint
+     * @private
+     */
+    _closeMobileOffcanvas() {
+        if (!isBelowBreakpoint('lg')) return;
+
+        const tocOffcanvas = document.getElementById('tocContents');
+        if (tocOffcanvas && typeof bootstrap !== 'undefined') {
+            const bsOffcanvas = bootstrap.Offcanvas.getInstance(tocOffcanvas);
+            if (bsOffcanvas) {
+                bsOffcanvas.hide();
+            }
+        }
+    }
+
+    /**
+     * Cleanup event listeners
+     */
+    destroy() {
+        // Note: We'd need to store bound handlers to properly remove them
+        // For now, this is a no-op since the page will reload anyway
+        console.log('SmoothScroll: Destroyed');
+    }
+}
+
+export default SmoothScroll;

data/assets/js/ui-enhancements.js

@@ -0,0 +1,194 @@
+/**
+ * UI/UX Enhancements for zer0-mistakes Theme
+ * Adds smooth scroll animations, intersection observer effects, and enhanced interactions
+ */
+
+(function() {
+  'use strict';
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  /**
+   * Initialize scroll animations for elements with animate-on-scroll class
+   */
+  function initScrollAnimations() {
+    if (prefersReducedMotion) return;
+
+    const animatedElements = document.querySelectorAll('.animate-on-scroll');
+    
+    if (!animatedElements.length) return;
+
+    const observerOptions = {
+      threshold: 0.1,
+      rootMargin: '0px 0px -50px 0px'
+    };
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          entry.target.style.opacity = '1';
+          entry.target.style.transform = 'translateY(0)';
+          observer.unobserve(entry.target);
+        }
+      });
+    }, observerOptions);
+
+    animatedElements.forEach(el => {
+      el.style.opacity = '0';
+      el.style.transform = 'translateY(30px)';
+      el.style.transition = 'opacity 0.6s ease-out, transform 0.6s ease-out';
+      observer.observe(el);
+    });
+  }
+
+  /**
+   * Enhance card interactions with parallax effect
+   */
+  function initCardParallax() {
+    if (prefersReducedMotion) return;
+
+    const cards = document.querySelectorAll('.feature-card, .card');
+    
+    cards.forEach(card => {
+      card.addEventListener('mousemove', function(e) {
+        const rect = card.getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const y = e.clientY - rect.top;
+        
+        const centerX = rect.width / 2;
+        const centerY = rect.height / 2;
+        
+        const rotateX = (y - centerY) / 20;
+        const rotateY = (centerX - x) / 20;
+        
+        card.style.transform = `perspective(1000px) rotateX(${rotateX}deg) rotateY(${rotateY}deg) translateY(-8px)`;
+      });
+      
+      card.addEventListener('mouseleave', function() {
+        card.style.transform = '';
+      });
+    });
+  }
+
+  /**
+   * Smooth scroll for anchor links
+   */
+  function initSmoothScroll() {
+    document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+      anchor.addEventListener('click', function(e) {
+        const href = this.getAttribute('href');
+        if (href === '#' || href === '') return;
+        
+        const target = document.querySelector(href);
+        if (target) {
+          e.preventDefault();
+          const offsetTop = target.offsetTop - 80; // Account for fixed navbar
+          
+          window.scrollTo({
+            top: offsetTop,
+            behavior: prefersReducedMotion ? 'auto' : 'smooth'
+          });
+        }
+      });
+    });
+  }
+
+  /**
+   * Add loading state to images
+   */
+  function initImageLoading() {
+    const images = document.querySelectorAll('img[loading="lazy"]');
+    
+    images.forEach(img => {
+      if (img.complete) {
+        img.classList.add('loaded');
+      } else {
+        img.addEventListener('load', function() {
+          this.classList.add('loaded');
+        });
+      }
+    });
+  }
+
+  /**
+   * Enhance button ripple effect
+   */
+  function initButtonRipples() {
+    if (prefersReducedMotion) return;
+
+    document.querySelectorAll('.btn').forEach(button => {
+      button.addEventListener('click', function(e) {
+        const ripple = document.createElement('span');
+        const rect = this.getBoundingClientRect();
+        const size = Math.max(rect.width, rect.height);
+        const x = e.clientX - rect.left - size / 2;
+        const y = e.clientY - rect.top - size / 2;
+        
+        ripple.style.width = ripple.style.height = size + 'px';
+        ripple.style.left = x + 'px';
+        ripple.style.top = y + 'px';
+        ripple.classList.add('ripple');
+        
+        this.appendChild(ripple);
+        
+        setTimeout(() => {
+          ripple.remove();
+        }, 600);
+      });
+    });
+  }
+
+  /**
+   * Add active state to navigation links on scroll
+   */
+  function initScrollSpy() {
+    const sections = document.querySelectorAll('section[id], [id^="get-started"], [id^="features"]');
+    const navLinks = document.querySelectorAll('a[href^="#"]');
+    
+    if (!sections.length || !navLinks.length) return;
+
+    const observerOptions = {
+      threshold: 0.3,
+      rootMargin: '-80px 0px -50% 0px'
+    };
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          const id = entry.target.getAttribute('id');
+          navLinks.forEach(link => {
+            link.classList.remove('active');
+            if (link.getAttribute('href') === `#${id}`) {
+              link.classList.add('active');
+            }
+          });
+        }
+      });
+    }, observerOptions);
+
+    sections.forEach(section => observer.observe(section));
+  }
+
+  /**
+   * Initialize all enhancements
+   */
+  function init() {
+    // Wait for DOM to be fully loaded
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', init);
+      return;
+    }
+
+    initScrollAnimations();
+    initCardParallax();
+    initSmoothScroll();
+    initImageLoading();
+    initButtonRipples();
+    initScrollSpy();
+  }
+
+  // Start initialization
+  init();
+})();
+