/**
 * RSL Scroll Progress Indicator
 *
 * Displays a visual progress bar showing how far the user has scrolled through
 * the page. Updates in real-time as the user scrolls, providing visual feedback
 * about content length and current position.
 *
 * @fileoverview Scroll position indicator with responsive width calculation
 * @version 1.0.0
 * @license MIT
 *
 * Key Features:
 * - Real-time scroll position tracking
 * - Accurate percentage calculation including scroll offset
 * - Handles both html and body scroll positions (browser compatibility)
 * - Smooth visual updates via CSS transitions
 * - Minimal performance impact using efficient calculations
 * - Works with fixed/sticky navigation headers
 *
 * Usage:
 * // HTML: Add progress bar element (typically in header)
 * <div class="scroll-progress"></div>
 *
 * // CSS: Style the progress bar (position, height, color)
 * .scroll-progress {
 *   position: fixed;
 *   top: 0;
 *   left: 0;
 *   height: 3px;
 *   background: var(--primary-color);
 *   width: 0%;
 *   transition: width 0.1s ease;
 *   z-index: 1000;
 * }
 *
 * // JavaScript: Include this script (no initialization required)
 *
 * Public API:
 * - Progress bar width updated via inline style: style.width
 * - Target element: .scroll-progress
 * - Width range: 0% to 100%
 */

(function() {
    'use strict';

    /**
     * Progress bar element cached for performance
     * @type {HTMLElement|null}
     */
    let progressBar = null;

    /**
     * Calculate scroll progress as a percentage
     *
     * Computes how far the user has scrolled through the document by comparing
     * current scroll position to total scrollable height. Handles different
     * browser implementations (documentElement vs body).
     *
     * @returns {number} Scroll progress percentage (0-100)
     *
     * @example
     * const progress = calculateScrollProgress();
     * // Returns: 0 at top, 100 at bottom, 50 at halfway point
     */
    function calculateScrollProgress() {
        // Current scroll position (handles browser differences)
        const scrollTop = document.documentElement.scrollTop || document.body.scrollTop;

        // Total scrollable height (total height minus viewport height)
        const scrollHeight = (document.documentElement.scrollHeight || document.body.scrollHeight) -
                           document.documentElement.clientHeight;

        // Calculate percentage (avoid division by zero)
        const scrollPercentage = scrollHeight > 0 ? (scrollTop / scrollHeight) * 100 : 0;

        return scrollPercentage;
    }

    /**
     * Update progress bar width based on scroll position
     *
     * Calculates current scroll percentage and applies it to the progress bar's
     * width style. Called on every scroll event for real-time updates.
     *
     * @returns {void}
     *
     * @example
     * // Called automatically on scroll
     * // Updates: <div class="scroll-progress" style="width: 45.23%"></div>
     */
    function updateScrollProgress() {
        // Cache progress bar element on first call
        if (!progressBar) {
            progressBar = document.querySelector('.scroll-progress');

            // If progress bar doesn't exist, remove listener to save resources
            if (!progressBar) {
                window.removeEventListener('scroll', updateScrollProgress);
                return;
            }
        }

        const percentage = calculateScrollProgress();
        progressBar.style.width = percentage + '%';
    }

    /**
     * Initialize scroll progress tracking
     *
     * Sets up scroll event listener and performs initial calculation.
     * Uses passive listener for better scroll performance.
     */
    function init() {
        // Initial update on page load
        updateScrollProgress();

        // Update on scroll (passive for better performance)
        window.addEventListener('scroll', updateScrollProgress, { passive: true });
    }

    /**
     * Auto-initialize on DOM ready or immediately if already loaded
     */
    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', init);
    } else {
        init();
    }

})();
