jekyll-theme-zer0 0.15.2 → 0.17.0

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;

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/scripts/README.md

@@ -91,7 +91,14 @@ Options:
   --dry-run           Preview without changes
   --collection TYPE   Generate for specific collection (posts, docs, etc.)
   -f, --file PATH     Process specific file
-  --provider PROVIDER Use specific AI provider (openai)
+  --provider PROVIDER Use specific AI provider (openai, stability, xai)
+  --assets-prefix     Custom assets path prefix (default: /assets)
+  --no-auto-prefix    Disable automatic path prefixing
+
+AI Providers:
+  openai    - OpenAI DALL-E (requires OPENAI_API_KEY)
+  stability - Stability AI (requires STABILITY_API_KEY)
+  xai       - xAI Grok image generation (requires XAI_API_KEY)
 ```
 
 #### `install-preview-generator`