jekyll-theme-zer0 0.16.0 → 0.17.0

data/assets/js/modules/navigation/config.js

@@ -0,0 +1,149 @@
+/**
+ * ===================================================================
+ * NAVIGATION CONFIG - Shared Configuration for Navigation Modules
+ * ===================================================================
+ * 
+ * File: config.js
+ * Path: assets/js/modules/navigation/config.js
+ * Purpose: Centralized configuration for all navigation modules
+ * 
+ * Usage:
+ *   import { config } from './config.js';
+ *   const toc = document.querySelector(config.selectors.toc);
+ * 
+ * ===================================================================
+ */
+
+export const config = {
+    // ===================================================================
+    // DOM SELECTORS
+    // ===================================================================
+    selectors: {
+        // Table of Contents
+        toc: '#TableOfContents',
+        tocLinks: '#TableOfContents a',
+        tocContainer: '.bd-toc .offcanvas-body',
+        
+        // Sidebars
+        leftSidebar: '#bdSidebar',
+        rightSidebar: '#tocContents',
+        
+        // Content areas
+        mainContent: '.bd-content',
+        
+        // Navigation elements
+        navTree: '.nav-tree',
+        navTreeToggle: '[data-nav-toggle]',
+        
+        // Offcanvas
+        offcanvas: '.offcanvas'
+    },
+
+    // ===================================================================
+    // SCROLL SPY SETTINGS
+    // ===================================================================
+    scrollSpy: {
+        // Root margin for Intersection Observer
+        // Negative values account for fixed headers
+        rootMargin: '-80px 0px -80px 0px',
+        
+        // Intersection threshold levels
+        threshold: [0, 0.25, 0.5, 0.75, 1]
+    },
+
+    // ===================================================================
+    // SMOOTH SCROLL SETTINGS
+    // ===================================================================
+    smoothScroll: {
+        // Offset for fixed headers when scrolling to anchor
+        offset: 80,
+        
+        // Scroll behavior
+        behavior: 'smooth'
+    },
+
+    // ===================================================================
+    // KEYBOARD SHORTCUTS
+    // ===================================================================
+    keyboard: {
+        // Enable/disable keyboard shortcuts
+        enabled: true,
+        
+        // Key mappings
+        keys: {
+            previousSection: '[',
+            nextSection: ']',
+            search: '/',
+            toggleSidebar: 'b',
+            toggleToc: 't'
+        }
+    },
+
+    // ===================================================================
+    // SWIPE GESTURES
+    // ===================================================================
+    gestures: {
+        // Enable/disable swipe gestures
+        enabled: true,
+        
+        // Minimum distance (px) for swipe to register
+        threshold: 50,
+        
+        // Edge detection zone (px) for sidebar swipes
+        edgeZone: 50
+    },
+
+    // ===================================================================
+    // SIDEBAR STATE PERSISTENCE
+    // ===================================================================
+    state: {
+        // localStorage key prefix
+        storagePrefix: 'zer0-nav-',
+        
+        // Keys for different state values
+        keys: {
+            expandedNodes: 'expanded-nodes',
+            sidebarOpen: 'sidebar-open',
+            tocOpen: 'toc-open'
+        }
+    },
+
+    // ===================================================================
+    // DEBOUNCE/THROTTLE TIMINGS
+    // ===================================================================
+    timing: {
+        debounceDelay: 100,
+        scrollDebounce: 50
+    },
+
+    // ===================================================================
+    // BREAKPOINTS (match Bootstrap 5)
+    // ===================================================================
+    breakpoints: {
+        sm: 576,
+        md: 768,
+        lg: 992,
+        xl: 1200,
+        xxl: 1400
+    }
+};
+
+/**
+ * Check if viewport is below a breakpoint
+ * @param {string} breakpoint - Breakpoint name (sm, md, lg, xl, xxl)
+ * @returns {boolean}
+ */
+export function isBelowBreakpoint(breakpoint) {
+    return window.innerWidth < config.breakpoints[breakpoint];
+}
+
+/**
+ * Check if viewport is at or above a breakpoint
+ * @param {string} breakpoint - Breakpoint name (sm, md, lg, xl, xxl)
+ * @returns {boolean}
+ */
+export function isAtOrAboveBreakpoint(breakpoint) {
+    return window.innerWidth >= config.breakpoints[breakpoint];
+}
+
+export default config;

data/assets/js/modules/navigation/focus.js

@@ -0,0 +1,189 @@
+/**
+ * ===================================================================
+ * FOCUS MANAGER - Accessibility Enhancements
+ * ===================================================================
+ * 
+ * File: focus.js
+ * Path: assets/js/modules/navigation/focus.js
+ * Purpose: Focus management for accessibility in navigation components
+ * 
+ * Features:
+ * - Returns focus to trigger element when offcanvas closes
+ * - Manages focus trap in modal/offcanvas contexts
+ * - Provides focus ring styling hooks
+ * 
+ * Usage:
+ *   import { FocusManager } from './focus.js';
+ *   const focus = new FocusManager();
+ * 
+ * ===================================================================
+ */
+
+import { config } 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 FocusManager {
+    constructor() {
+        this._boundHandleHidden = this._handleOffcanvasHidden.bind(this);
+        this._init();
+    }
+
+    /**
+     * Initialize focus management
+     * @private
+     */
+    _init() {
+        // Handle focus return when offcanvas closes
+        const offcanvasElements = getElements(config.selectors.offcanvas);
+        
+        offcanvasElements.forEach(offcanvas => {
+            offcanvas.addEventListener('hidden.bs.offcanvas', this._boundHandleHidden);
+        });
+
+        // Add focus-visible polyfill behavior
+        this._setupFocusVisible();
+
+        console.log(`FocusManager: Initialized with ${offcanvasElements.length} offcanvas elements`);
+    }
+
+    /**
+     * Handle offcanvas hidden event - return focus to trigger
+     * @private
+     * @param {Event} event
+     */
+    _handleOffcanvasHidden(event) {
+        const offcanvas = event.target;
+        this.returnFocus(offcanvas);
+    }
+
+    /**
+     * Return focus to the trigger element that opened an offcanvas
+     * @param {Element} offcanvas - The offcanvas element
+     */
+    returnFocus(offcanvas) {
+        const triggerId = offcanvas.id;
+        
+        // Find the trigger button that opened this offcanvas
+        const trigger = document.querySelector(
+            `[data-bs-target="#${triggerId}"], [href="#${triggerId}"]`
+        );
+        
+        if (trigger) {
+            // Small delay to ensure offcanvas animation completes
+            requestAnimationFrame(() => {
+                trigger.focus();
+            });
+        }
+    }
+
+    /**
+     * Setup focus-visible behavior for keyboard users
+     * @private
+     */
+    _setupFocusVisible() {
+        // Add class to body when user is navigating with keyboard
+        let hadKeyboardEvent = false;
+        
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Tab') {
+                hadKeyboardEvent = true;
+                document.body.classList.add('keyboard-nav');
+            }
+        });
+
+        document.addEventListener('mousedown', () => {
+            hadKeyboardEvent = false;
+            document.body.classList.remove('keyboard-nav');
+        });
+    }
+
+    /**
+     * Focus the first focusable element within a container
+     * @param {Element} container
+     */
+    focusFirst(container) {
+        const focusable = container.querySelector(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        if (focusable) {
+            focusable.focus();
+        }
+    }
+
+    /**
+     * Focus the last focusable element within a container
+     * @param {Element} container
+     */
+    focusLast(container) {
+        const focusables = container.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        if (focusables.length > 0) {
+            focusables[focusables.length - 1].focus();
+        }
+    }
+
+    /**
+     * Trap focus within a container (for modals/offcanvas)
+     * @param {Element} container
+     * @returns {Function} Cleanup function to remove trap
+     */
+    trapFocus(container) {
+        const focusableElements = container.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        
+        const firstFocusable = focusableElements[0];
+        const lastFocusable = focusableElements[focusableElements.length - 1];
+
+        const handleKeydown = (e) => {
+            if (e.key !== 'Tab') return;
+
+            if (e.shiftKey) {
+                // Shift + Tab
+                if (document.activeElement === firstFocusable) {
+                    e.preventDefault();
+                    lastFocusable.focus();
+                }
+            } else {
+                // Tab
+                if (document.activeElement === lastFocusable) {
+                    e.preventDefault();
+                    firstFocusable.focus();
+                }
+            }
+        };
+
+        container.addEventListener('keydown', handleKeydown);
+
+        // Return cleanup function
+        return () => {
+            container.removeEventListener('keydown', handleKeydown);
+        };
+    }
+
+    /**
+     * Cleanup event listeners
+     */
+    destroy() {
+        const offcanvasElements = getElements(config.selectors.offcanvas);
+        offcanvasElements.forEach(offcanvas => {
+            offcanvas.removeEventListener('hidden.bs.offcanvas', this._boundHandleHidden);
+        });
+        console.log('FocusManager: Destroyed');
+    }
+}
+
+export default FocusManager;

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;