jekyll-theme-zer0 0.16.0 → 0.17.0

data/assets/js/modules/navigation/index.js

@@ -0,0 +1,227 @@
+/**
+ * ===================================================================
+ * NAVIGATION - Main Entry Point
+ * ===================================================================
+ * 
+ * File: index.js
+ * Path: assets/js/modules/navigation/index.js
+ * Purpose: Main orchestrator for all navigation modules
+ * 
+ * This module imports and initializes all navigation-related modules:
+ * - ScrollSpy: Highlights current section in TOC
+ * - SmoothScroll: Smooth anchor navigation
+ * - KeyboardShortcuts: Keyboard navigation
+ * - SwipeGestures: Mobile gesture support
+ * - FocusManager: Accessibility focus management
+ * - SidebarState: Persistence of sidebar state
+ * 
+ * Usage:
+ *   <script type="module" src="/assets/js/modules/navigation/index.js"></script>
+ * 
+ * Or import programmatically:
+ *   import { Navigation } from './modules/navigation/index.js';
+ *   const nav = new Navigation();
+ * 
+ * ===================================================================
+ */
+
+import { config } from './config.js';
+import { ScrollSpy } from './scroll-spy.js';
+import { SmoothScroll } from './smooth-scroll.js';
+import { KeyboardShortcuts } from './keyboard.js';
+import { SwipeGestures } from './gestures.js';
+import { FocusManager } from './focus.js';
+import { SidebarState } from './sidebar-state.js';
+
+/**
+ * Navigation Controller - Orchestrates all navigation modules
+ */
+export class Navigation {
+    constructor() {
+        this.modules = {};
+        this._initialized = false;
+    }
+
+    /**
+     * Initialize all navigation modules
+     * @returns {Navigation} this instance for chaining
+     */
+    init() {
+        if (this._initialized) {
+            console.warn('Navigation: Already initialized');
+            return this;
+        }
+
+        try {
+            // Initialize sidebar state first (other modules may depend on it)
+            this.modules.state = new SidebarState();
+            
+            // Initialize TOC-related modules only if TOC exists
+            const toc = document.querySelector(config.selectors.toc);
+            if (toc) {
+                this.modules.scrollSpy = new ScrollSpy();
+                this.modules.smoothScroll = new SmoothScroll();
+            } else {
+                console.log('Navigation: No TOC found, skipping scroll spy and smooth scroll');
+            }
+            
+            // Initialize keyboard shortcuts
+            this.modules.keyboard = new KeyboardShortcuts();
+            
+            // Initialize gesture support
+            this.modules.gestures = new SwipeGestures();
+            
+            // Initialize focus management
+            this.modules.focus = new FocusManager();
+
+            this._initialized = true;
+            
+            // Dispatch ready event
+            document.dispatchEvent(new CustomEvent('navigation:ready', {
+                detail: { 
+                    modules: Object.keys(this.modules)
+                }
+            }));
+
+            console.log('Navigation: Successfully initialized modules:', Object.keys(this.modules));
+            
+        } catch (error) {
+            console.error('Navigation: Initialization error', error);
+        }
+
+        return this;
+    }
+
+    /**
+     * Get a specific module instance
+     * @param {string} name - Module name
+     * @returns {Object|undefined}
+     */
+    getModule(name) {
+        return this.modules[name];
+    }
+
+    /**
+     * Get configuration
+     * @returns {Object}
+     */
+    getConfig() {
+        return config;
+    }
+
+    /**
+     * Scroll to a specific element
+     * @param {string|Element} target - Element ID or Element
+     * @param {number} [offset] - Optional scroll offset
+     */
+    scrollTo(target, offset) {
+        if (!this.modules.smoothScroll) return;
+        
+        if (typeof target === 'string') {
+            this.modules.smoothScroll.scrollToId(target, offset);
+        } else if (target instanceof Element) {
+            this.modules.smoothScroll.scrollToElement(target, offset);
+        }
+    }
+
+    /**
+     * Expand sidebar tree to show a specific item
+     * @param {string} targetId - ID of element to reveal
+     */
+    expandTo(targetId) {
+        if (this.modules.state) {
+            this.modules.state.expandPathTo(targetId);
+        }
+    }
+
+    /**
+     * Expand all sidebar tree nodes
+     */
+    expandAll() {
+        if (this.modules.state) {
+            this.modules.state.expandAll();
+        }
+    }
+
+    /**
+     * Collapse all sidebar tree nodes
+     */
+    collapseAll() {
+        if (this.modules.state) {
+            this.modules.state.collapseAll();
+        }
+    }
+
+    /**
+     * Get keyboard shortcuts for help display
+     * @returns {Object|null}
+     */
+    getShortcuts() {
+        if (this.modules.keyboard && this.modules.keyboard.getShortcuts) {
+            return this.modules.keyboard.getShortcuts();
+        }
+        return null;
+    }
+
+    /**
+     * Destroy all modules and cleanup
+     */
+    destroy() {
+        Object.values(this.modules).forEach(module => {
+            if (module && typeof module.destroy === 'function') {
+                module.destroy();
+            }
+        });
+        
+        this.modules = {};
+        this._initialized = false;
+        
+        document.dispatchEvent(new CustomEvent('navigation:destroyed'));
+        console.log('Navigation: Destroyed all modules');
+    }
+}
+
+// ===================================================================
+// AUTO-INITIALIZATION
+// ===================================================================
+
+/**
+ * Create and initialize navigation when DOM is ready
+ */
+function initNavigation() {
+    // Create global instance
+    window.zer0Navigation = new Navigation();
+    
+    // Check if Bootstrap is available
+    if (typeof bootstrap === 'undefined') {
+        console.warn('Navigation: Bootstrap not found, waiting for load event');
+        window.addEventListener('load', () => {
+            window.zer0Navigation.init();
+        });
+    } else {
+        window.zer0Navigation.init();
+    }
+}
+
+// Wait for DOM to be ready
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initNavigation);
+} else {
+    // DOM already loaded
+    initNavigation();
+}
+
+// ===================================================================
+// EXPORTS
+// ===================================================================
+
+// Export individual modules for advanced usage
+export { config } from './config.js';
+export { ScrollSpy } from './scroll-spy.js';
+export { SmoothScroll } from './smooth-scroll.js';
+export { KeyboardShortcuts } from './keyboard.js';
+export { SwipeGestures } from './gestures.js';
+export { FocusManager } from './focus.js';
+export { SidebarState } from './sidebar-state.js';
+
+export default Navigation;

data/assets/js/modules/navigation/keyboard.js

@@ -0,0 +1,237 @@
+/**
+ * ===================================================================
+ * KEYBOARD SHORTCUTS - Navigation Enhancements
+ * ===================================================================
+ * 
+ * File: keyboard.js
+ * Path: assets/js/modules/navigation/keyboard.js
+ * Purpose: Keyboard shortcuts for navigation and accessibility
+ * 
+ * Default Shortcuts:
+ * - [ : Navigate to previous section
+ * - ] : Navigate to next section
+ * - / : Focus search (when implemented)
+ * - b : Toggle left sidebar
+ * - t : Toggle TOC sidebar
+ * 
+ * Usage:
+ *   import { KeyboardShortcuts } from './keyboard.js';
+ *   const shortcuts = new KeyboardShortcuts();
+ * 
+ * ===================================================================
+ */
+
+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) {
+        return [];
+    }
+}
+
+export class KeyboardShortcuts {
+    constructor() {
+        if (!config.keyboard.enabled) {
+            console.log('KeyboardShortcuts: Disabled via config');
+            return;
+        }
+        
+        this.tocLinks = Array.from(getElements(config.selectors.tocLinks));
+        this.currentIndex = -1;
+        this._boundHandler = this._handleKeydown.bind(this);
+        
+        this._init();
+    }
+
+    /**
+     * Initialize keyboard event listeners
+     * @private
+     */
+    _init() {
+        document.addEventListener('keydown', this._boundHandler);
+        console.log('KeyboardShortcuts: Initialized');
+    }
+
+    /**
+     * Handle keydown events
+     * @private
+     * @param {KeyboardEvent} event
+     */
+    _handleKeydown(event) {
+        // Ignore if user is typing in an input
+        if (event.target.matches('input, textarea, select, [contenteditable="true"]')) {
+            return;
+        }
+
+        const { keys } = config.keyboard;
+
+        switch(event.key) {
+            case keys.previousSection:
+                event.preventDefault();
+                this._navigatePrevious();
+                break;
+                
+            case keys.nextSection:
+                event.preventDefault();
+                this._navigateNext();
+                break;
+                
+            case keys.search:
+                event.preventDefault();
+                this._focusSearch();
+                break;
+                
+            case keys.toggleSidebar:
+                // Only handle if not typing
+                if (!event.ctrlKey && !event.metaKey && !event.altKey) {
+                    event.preventDefault();
+                    this._toggleSidebar();
+                }
+                break;
+                
+            case keys.toggleToc:
+                // Only handle if not typing
+                if (!event.ctrlKey && !event.metaKey && !event.altKey) {
+                    event.preventDefault();
+                    this._toggleToc();
+                }
+                break;
+        }
+    }
+
+    /**
+     * Navigate to previous section
+     * @private
+     */
+    _navigatePrevious() {
+        this._updateCurrentIndex();
+
+        if (this.currentIndex > 0) {
+            this.currentIndex--;
+            this._navigateToIndex(this.currentIndex);
+        }
+    }
+
+    /**
+     * Navigate to next section
+     * @private
+     */
+    _navigateNext() {
+        this._updateCurrentIndex();
+
+        if (this.currentIndex < this.tocLinks.length - 1) {
+            this.currentIndex++;
+            this._navigateToIndex(this.currentIndex);
+        }
+    }
+
+    /**
+     * Update current index based on active link
+     * @private
+     */
+    _updateCurrentIndex() {
+        const activeLink = document.querySelector(`${config.selectors.tocLinks}.active`);
+        if (activeLink) {
+            this.currentIndex = this.tocLinks.indexOf(activeLink);
+        }
+    }
+
+    /**
+     * Navigate to a specific index
+     * @private
+     * @param {number} index
+     */
+    _navigateToIndex(index) {
+        const link = this.tocLinks[index];
+        if (link) {
+            link.click();
+            
+            // Dispatch event for tracking
+            document.dispatchEvent(new CustomEvent('navigation:keyboardNav', {
+                detail: { 
+                    direction: index > this.currentIndex ? 'next' : 'previous',
+                    index: index
+                }
+            }));
+        }
+    }
+
+    /**
+     * Focus search input
+     * @private
+     */
+    _focusSearch() {
+        const searchInput = document.querySelector('#search-input, [data-search-input]');
+        if (searchInput) {
+            searchInput.focus();
+        } else {
+            console.log('KeyboardShortcuts: Search not yet implemented');
+            // Dispatch event so other modules can handle
+            document.dispatchEvent(new CustomEvent('navigation:searchRequest'));
+        }
+    }
+
+    /**
+     * Toggle left sidebar
+     * @private
+     */
+    _toggleSidebar() {
+        const sidebar = document.querySelector(config.selectors.leftSidebar);
+        if (sidebar && typeof bootstrap !== 'undefined') {
+            const bsOffcanvas = bootstrap.Offcanvas.getOrCreateInstance(sidebar);
+            bsOffcanvas.toggle();
+            
+            document.dispatchEvent(new CustomEvent('navigation:sidebarToggle', {
+                detail: { sidebar: 'left' }
+            }));
+        }
+    }
+
+    /**
+     * Toggle TOC sidebar
+     * @private
+     */
+    _toggleToc() {
+        const toc = document.querySelector(config.selectors.rightSidebar);
+        if (toc && typeof bootstrap !== 'undefined') {
+            const bsOffcanvas = bootstrap.Offcanvas.getOrCreateInstance(toc);
+            bsOffcanvas.toggle();
+            
+            document.dispatchEvent(new CustomEvent('navigation:sidebarToggle', {
+                detail: { sidebar: 'toc' }
+            }));
+        }
+    }
+
+    /**
+     * Get available shortcuts for help display
+     * @returns {Object} Map of key to description
+     */
+    getShortcuts() {
+        const { keys } = config.keyboard;
+        return {
+            [keys.previousSection]: 'Previous section',
+            [keys.nextSection]: 'Next section',
+            [keys.search]: 'Focus search',
+            [keys.toggleSidebar]: 'Toggle sidebar',
+            [keys.toggleToc]: 'Toggle table of contents'
+        };
+    }
+
+    /**
+     * Cleanup event listeners
+     */
+    destroy() {
+        document.removeEventListener('keydown', this._boundHandler);
+        console.log('KeyboardShortcuts: Destroyed');
+    }
+}
+
+export default KeyboardShortcuts;

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

@@ -0,0 +1,219 @@
+/**
+ * ===================================================================
+ * SCROLL SPY - Intersection Observer Implementation
+ * ===================================================================
+ * 
+ * File: scroll-spy.js
+ * Path: assets/js/modules/navigation/scroll-spy.js
+ * Purpose: Track visible sections and highlight corresponding TOC links
+ * 
+ * Features:
+ * - Intersection Observer-based (better performance than scroll events)
+ * - Active link highlighting with smooth transitions
+ * - Auto-scroll TOC to keep active link visible
+ * 
+ * Usage:
+ *   import { ScrollSpy } from './scroll-spy.js';
+ *   const scrollSpy = new ScrollSpy();
+ * 
+ * ===================================================================
+ */
+
+import { config } from './config.js';
+
+/**
+ * Get element safely with error handling
+ * @param {string} selector - CSS selector
+ * @returns {Element|null}
+ */
+function getElement(selector) {
+    try {
+        return document.querySelector(selector);
+    } catch (error) {
+        console.warn(`ScrollSpy: Element not found - ${selector}`);
+        return null;
+    }
+}
+
+/**
+ * Get all elements safely with error handling
+ * @param {string} selector - CSS selector
+ * @returns {NodeList}
+ */
+function getElements(selector) {
+    try {
+        return document.querySelectorAll(selector);
+    } catch (error) {
+        console.warn(`ScrollSpy: Elements not found - ${selector}`);
+        return [];
+    }
+}
+
+export class ScrollSpy {
+    constructor() {
+        this.tocLinks = getElements(config.selectors.tocLinks);
+        this.headings = this._getHeadings();
+        this.currentActive = null;
+        this.observer = null;
+        
+        if (this.headings.length === 0 || this.tocLinks.length === 0) {
+            console.log('ScrollSpy: No TOC or headings found, skipping initialization');
+            return;
+        }
+
+        this._init();
+    }
+
+    /**
+     * Get all headings that have corresponding TOC links
+     * @private
+     * @returns {Array<{element: Element, link: Element, id: string}>}
+     */
+    _getHeadings() {
+        const headings = [];
+        this.tocLinks.forEach(link => {
+            const href = link.getAttribute('href');
+            if (href && href.startsWith('#')) {
+                const id = href.substring(1);
+                const heading = document.getElementById(id);
+                if (heading) {
+                    headings.push({
+                        element: heading,
+                        link: link,
+                        id: id
+                    });
+                }
+            }
+        });
+        return headings;
+    }
+
+    /**
+     * Initialize Intersection Observer
+     * @private
+     */
+    _init() {
+        const observerOptions = {
+            root: null,
+            rootMargin: config.scrollSpy.rootMargin,
+            threshold: config.scrollSpy.threshold
+        };
+
+        this.observer = new IntersectionObserver(
+            entries => this._handleIntersection(entries),
+            observerOptions
+        );
+
+        // Observe all headings
+        this.headings.forEach(heading => {
+            this.observer.observe(heading.element);
+        });
+
+        console.log(`ScrollSpy: Observing ${this.headings.length} headings`);
+    }
+
+    /**
+     * Handle intersection events
+     * @private
+     * @param {IntersectionObserverEntry[]} entries
+     */
+    _handleIntersection(entries) {
+        // Find the most visible heading
+        let mostVisible = null;
+        let maxRatio = 0;
+
+        entries.forEach(entry => {
+            if (entry.isIntersecting && entry.intersectionRatio > maxRatio) {
+                maxRatio = entry.intersectionRatio;
+                mostVisible = this.headings.find(h => h.element === entry.target);
+            }
+        });
+
+        // If we found a visible heading, activate it
+        if (mostVisible) {
+            this._setActiveLink(mostVisible.link);
+        }
+    }
+
+    /**
+     * Set active link with visual feedback
+     * @private
+     * @param {Element} link
+     */
+    _setActiveLink(link) {
+        if (this.currentActive === link) return;
+
+        // Remove previous active state
+        this.tocLinks.forEach(l => l.classList.remove('active'));
+
+        // Add active state
+        if (link) {
+            link.classList.add('active');
+            this.currentActive = link;
+
+            // Scroll TOC to show active link (if needed)
+            this._scrollTocToActiveLink(link);
+
+            // Dispatch custom event for other modules
+            document.dispatchEvent(new CustomEvent('navigation:sectionChange', {
+                detail: { 
+                    link: link,
+                    href: link.getAttribute('href')
+                }
+            }));
+        }
+    }
+
+    /**
+     * Scroll TOC container to show active link
+     * @private
+     * @param {Element} link
+     */
+    _scrollTocToActiveLink(link) {
+        const tocContainer = getElement(config.selectors.tocContainer);
+        if (!tocContainer) return;
+
+        const linkRect = link.getBoundingClientRect();
+        const containerRect = tocContainer.getBoundingClientRect();
+
+        // Check if link is out of view
+        if (linkRect.top < containerRect.top || linkRect.bottom > containerRect.bottom) {
+            link.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+        }
+    }
+
+    /**
+     * Manually set active section by ID
+     * @param {string} id - Heading ID to activate
+     */
+    setActiveById(id) {
+        const heading = this.headings.find(h => h.id === id);
+        if (heading) {
+            this._setActiveLink(heading.link);
+        }
+    }
+
+    /**
+     * Get current active heading
+     * @returns {{element: Element, link: Element, id: string}|null}
+     */
+    getActive() {
+        if (!this.currentActive) return null;
+        return this.headings.find(h => h.link === this.currentActive) || null;
+    }
+
+    /**
+     * Cleanup observer
+     */
+    destroy() {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+        this.tocLinks.forEach(l => l.classList.remove('active'));
+        this.currentActive = null;
+        console.log('ScrollSpy: Destroyed');
+    }
+}
+
+export default ScrollSpy;