jekyll-theme-zer0 0.15.2 → 0.17.0

data/assets/js/modules/navigation/gestures.js

@@ -0,0 +1,179 @@
+/**
+ * ===================================================================
+ * SWIPE GESTURES - Mobile Offcanvas Control
+ * ===================================================================
+ * 
+ * File: gestures.js
+ * Path: assets/js/modules/navigation/gestures.js
+ * Purpose: Touch gesture support for sidebar navigation on mobile
+ * 
+ * Features:
+ * - Swipe from left edge to open left sidebar
+ * - Swipe from right edge to open TOC sidebar
+ * - Configurable threshold and edge zones
+ * 
+ * Usage:
+ *   import { SwipeGestures } from './gestures.js';
+ *   const gestures = new SwipeGestures();
+ * 
+ * ===================================================================
+ */
+
+import { config, isBelowBreakpoint } from './config.js';
+
+export class SwipeGestures {
+    constructor() {
+        if (!config.gestures.enabled) {
+            console.log('SwipeGestures: Disabled via config');
+            return;
+        }
+        
+        this.startX = 0;
+        this.startY = 0;
+        this.distX = 0;
+        this.distY = 0;
+        
+        // Bound handlers for cleanup
+        this._boundTouchStart = this._handleTouchStart.bind(this);
+        this._boundTouchMove = this._handleTouchMove.bind(this);
+        this._boundTouchEnd = this._handleTouchEnd.bind(this);
+        
+        this._init();
+    }
+
+    /**
+     * Initialize touch event listeners
+     * @private
+     */
+    _init() {
+        document.addEventListener('touchstart', this._boundTouchStart, { passive: true });
+        document.addEventListener('touchmove', this._boundTouchMove, { passive: true });
+        document.addEventListener('touchend', this._boundTouchEnd);
+        
+        console.log('SwipeGestures: Initialized');
+    }
+
+    /**
+     * Handle touch start
+     * @private
+     * @param {TouchEvent} event
+     */
+    _handleTouchStart(event) {
+        const touch = event.touches[0];
+        this.startX = touch.clientX;
+        this.startY = touch.clientY;
+        this.distX = 0;
+        this.distY = 0;
+    }
+
+    /**
+     * Handle touch move
+     * @private
+     * @param {TouchEvent} event
+     */
+    _handleTouchMove(event) {
+        if (!this.startX || !this.startY) return;
+
+        const touch = event.touches[0];
+        this.distX = touch.clientX - this.startX;
+        this.distY = touch.clientY - this.startY;
+    }
+
+    /**
+     * Handle touch end
+     * @private
+     * @param {TouchEvent} event
+     */
+    _handleTouchEnd(event) {
+        const { threshold, edgeZone } = config.gestures;
+        
+        // Check if swipe distance meets threshold
+        if (Math.abs(this.distX) < threshold) {
+            this._reset();
+            return;
+        }
+
+        // Only handle horizontal swipes (not vertical scroll)
+        if (Math.abs(this.distX) > Math.abs(this.distY)) {
+            if (this.distX > 0) {
+                this._handleSwipeRight();
+            } else {
+                this._handleSwipeLeft();
+            }
+        }
+
+        this._reset();
+    }
+
+    /**
+     * Handle swipe right (open left sidebar)
+     * @private
+     */
+    _handleSwipeRight() {
+        const { edgeZone } = config.gestures;
+        
+        // Only if swipe started from left edge
+        if (this.startX > edgeZone) return;
+        
+        // Only on mobile
+        if (!isBelowBreakpoint('lg')) return;
+
+        const leftSidebar = document.querySelector(config.selectors.leftSidebar);
+        if (leftSidebar && typeof bootstrap !== 'undefined') {
+            const bsOffcanvas = bootstrap.Offcanvas.getOrCreateInstance(leftSidebar);
+            bsOffcanvas.show();
+            
+            document.dispatchEvent(new CustomEvent('navigation:swipe', {
+                detail: { direction: 'right', sidebar: 'left' }
+            }));
+        }
+    }
+
+    /**
+     * Handle swipe left (open right/TOC sidebar)
+     * @private
+     */
+    _handleSwipeLeft() {
+        const { edgeZone } = config.gestures;
+        const windowWidth = window.innerWidth;
+        
+        // Only if swipe started from right edge
+        if (this.startX < windowWidth - edgeZone) return;
+        
+        // Only on mobile
+        if (!isBelowBreakpoint('lg')) return;
+
+        const rightSidebar = document.querySelector(config.selectors.rightSidebar);
+        if (rightSidebar && typeof bootstrap !== 'undefined') {
+            const bsOffcanvas = bootstrap.Offcanvas.getOrCreateInstance(rightSidebar);
+            bsOffcanvas.show();
+            
+            document.dispatchEvent(new CustomEvent('navigation:swipe', {
+                detail: { direction: 'left', sidebar: 'toc' }
+            }));
+        }
+    }
+
+    /**
+     * Reset touch tracking state
+     * @private
+     */
+    _reset() {
+        this.startX = 0;
+        this.startY = 0;
+        this.distX = 0;
+        this.distY = 0;
+    }
+
+    /**
+     * Cleanup event listeners
+     */
+    destroy() {
+        document.removeEventListener('touchstart', this._boundTouchStart);
+        document.removeEventListener('touchmove', this._boundTouchMove);
+        document.removeEventListener('touchend', this._boundTouchEnd);
+        console.log('SwipeGestures: Destroyed');
+    }
+}
+
+export default SwipeGestures;

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;