jekyll-theme-zer0 0.16.0 → 0.17.0

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/migrate-nav-modes.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# ===================================================================
+# MIGRATE NAV MODES - Update Front Matter Navigation Values
+# ===================================================================
+#
+# File: migrate-nav-modes.sh
+# Path: scripts/migrate-nav-modes.sh
+# Purpose: Update front matter nav values from old to new modes
+#
+# Migration Map:
+#   dynamic    → auto
+#   searchCats → categories
+#   docs       → tree
+#   about      → tree
+#   quickstart → tree
+#   main       → tree
+#
+# Usage:
+#   ./scripts/migrate-nav-modes.sh           # Dry run (preview changes)
+#   ./scripts/migrate-nav-modes.sh --apply   # Apply changes
+#
+# ===================================================================
+
+set -eo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Script configuration
+PAGES_DIR="pages"
+DRY_RUN=true
+
+# Parse arguments
+if [[ "${1:-}" == "--apply" ]]; then
+    DRY_RUN=false
+fi
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}  Navigation Mode Migration Script${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+
+if $DRY_RUN; then
+    echo -e "${YELLOW}Running in DRY RUN mode. No files will be modified.${NC}"
+    echo -e "${YELLOW}Use --apply to make actual changes.${NC}"
+else
+    echo -e "${RED}Running in APPLY mode. Files will be modified.${NC}"
+fi
+echo ""
+
+# Migration patterns (old → new)
+# Using simple arrays instead of associative arrays for compatibility
+OLD_PATTERNS=("nav: dynamic" "nav: searchCats")
+NEW_PATTERNS=("nav: auto" "nav: categories")
+
+# Files that explicitly set nav values (not inherited from _config.yml)
+EXPLICIT_NAV_PATTERNS=(
+    "nav: dynamic"
+    "nav: searchCats"
+    "nav: docs"
+    "nav: about"
+    "nav: quickstart"
+    "nav: main"
+)
+
+# Count changes
+TOTAL_FILES=0
+TOTAL_CHANGES=0
+
+echo -e "${BLUE}Scanning for files with explicit nav values...${NC}"
+echo ""
+
+# Find all markdown files
+while IFS= read -r -d '' file; do
+    file_changes=0
+    
+    # Check if file has any nav patterns
+    for pattern in "${EXPLICIT_NAV_PATTERNS[@]}"; do
+        if grep -q "$pattern" "$file" 2>/dev/null; then
+            ((file_changes++)) || true
+        fi
+    done
+    
+    if [[ $file_changes -gt 0 ]]; then
+        ((TOTAL_FILES++)) || true
+        echo -e "${GREEN}Found:${NC} $file"
+        
+        # Show what would change
+        for i in "${!OLD_PATTERNS[@]}"; do
+            old_pattern="${OLD_PATTERNS[$i]}"
+            new_pattern="${NEW_PATTERNS[$i]}"
+            if grep -q "$old_pattern" "$file" 2>/dev/null; then
+                echo -e "  ${YELLOW}Change:${NC} '$old_pattern' → '$new_pattern'"
+                ((TOTAL_CHANGES++)) || true
+                
+                if ! $DRY_RUN; then
+                    # Apply the change using sed
+                    if [[ "$OSTYPE" == "darwin"* ]]; then
+                        sed -i '' "s/$old_pattern/$new_pattern/g" "$file"
+                    else
+                        sed -i "s/$old_pattern/$new_pattern/g" "$file"
+                    fi
+                fi
+            fi
+        done
+        
+        # Check for named nav files that should use tree mode
+        # Note: These are trickier because we want to keep the YAML file reference
+        # but change how the template interprets them
+        for named_nav in "docs" "about" "quickstart" "main"; do
+            if grep -q "nav: $named_nav" "$file" 2>/dev/null; then
+                echo -e "  ${BLUE}Note:${NC} 'nav: $named_nav' - YAML file will be used with tree mode"
+                # No automatic migration - sidebar-left.html handles this via fallthrough
+            fi
+        done
+        
+        echo ""
+    fi
+done < <(find "$PAGES_DIR" -name "*.md" -print0 2>/dev/null)
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}  Summary${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+echo -e "Files scanned:  ${GREEN}$(find "$PAGES_DIR" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')${NC}"
+echo -e "Files affected: ${GREEN}$TOTAL_FILES${NC}"
+echo -e "Changes made:   ${GREEN}$TOTAL_CHANGES${NC}"
+echo ""
+
+if $DRY_RUN; then
+    echo -e "${YELLOW}This was a dry run. To apply changes, run:${NC}"
+    echo -e "  ${GREEN}./scripts/migrate-nav-modes.sh --apply${NC}"
+else
+    echo -e "${GREEN}Migration complete!${NC}"
+fi
+
+echo ""
+echo -e "${BLUE}Navigation Mode Reference:${NC}"
+echo "  auto       - Auto-generated from collection documents"
+echo "  tree       - YAML-defined hierarchical navigation"
+echo "  categories - Category-based grouping"
+echo ""

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-12-20 00:00:00.000000000 Z
+date: 2025-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -80,9 +80,11 @@ files:
 - _data/README.md
 - _data/authors.yml
 - _data/content_statistics.yml
+- _data/features.yml
 - _data/generate_statistics.rb
 - _data/generate_statistics.sh
 - _data/github-actions-example.yml
+- _data/navigation/README.md
 - _data/navigation/about.yml
 - _data/navigation/docs.yml
 - _data/navigation/home.yml
@@ -127,6 +129,7 @@ files:
 - _includes/landing/landing-install-cards.html
 - _includes/landing/landing-quick-links.html
 - _includes/navigation/breadcrumbs.html
+- _includes/navigation/nav-tree.html
 - _includes/navigation/nav_list.html
 - _includes/navigation/navbar.html
 - _includes/navigation/sidebar-categories.html
@@ -157,6 +160,7 @@ files:
 - _plugins/preview_image_generator.rb
 - _plugins/theme_version.rb
 - _sass/core/_docs.scss
+- _sass/core/_nav-tree.scss
 - _sass/core/_syntax.scss
 - _sass/core/_theme.scss
 - _sass/core/_variables.scss
@@ -202,12 +206,19 @@ files:
 - assets/js/color-modes.js
 - assets/js/docs.min.js
 - assets/js/halfmoon.js
+- assets/js/modules/navigation/config.js
+- assets/js/modules/navigation/focus.js
+- assets/js/modules/navigation/gestures.js
+- assets/js/modules/navigation/index.js
+- assets/js/modules/navigation/keyboard.js
+- assets/js/modules/navigation/scroll-spy.js
+- assets/js/modules/navigation/sidebar-state.js
+- assets/js/modules/navigation/smooth-scroll.js
 - assets/js/myScript.js
 - assets/js/nanobar.min.js
 - assets/js/particles-source.js
 - assets/js/particles.js
 - assets/js/side-bar-folders.js
-- assets/js/sidebar.js
 - assets/particles.json
 - scripts/README.md
 - scripts/analyze-commits.sh
@@ -231,6 +242,7 @@ files:
 - scripts/lib/preview_generator.py
 - scripts/lib/validation.sh
 - scripts/lib/version.sh
+- scripts/migrate-nav-modes.sh
 - scripts/release
 - scripts/setup.sh
 - scripts/test-auto-version.sh