Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

10.8 KB
Raw Blame
/**
 * Help System Service
 * Manages collapsible help panels and dismissal preferences
 *
 * URL Security Note: This service only uses internal relative URLs (/settings/api/*)
 * for the SettingsManager API. No external URLs are handled.
 * URLValidator is not required as all URLs are hardcoded internal API paths.
 *
 * Dismissal preferences are stored in the backend via SettingsManager API
 * for consistency with other UI dismissals and encrypted storage.
 * Collapsed state uses localStorage for session persistence only.
 */

const HelpService = (function() {
    'use strict';

    // Storage key prefix for dismissed panels (backend setting key)
    const STORAGE_PREFIX = 'app.ui.help_dismissed_';

    // Internal API base path (relative URL - no external URLs)
    const SETTINGS_API_BASE = '/settings/api/';

    // Cache for dismissed panel states
    const dismissedCache = {};
    let initialized = false;

    /**
     * Toggle a help panel's collapsed state
     * @param {string} panelId - The panel ID to toggle
     */
    function togglePanel(panelId) {
        const panel = document.getElementById('help-panel-' + panelId);
        if (!panel) {
            SafeLogger.warn('Help panel not found:', panelId);
            return;
        }

        const isCollapsed = panel.classList.toggle('collapsed');
        const header = panel.querySelector('.ldr-help-panel-header');

        if (header) {
            header.setAttribute('aria-expanded', !isCollapsed);
        }

        // Store collapsed preference in localStorage for session persistence
        // (this is UI state, not a user preference, so localStorage is appropriate)
        try {
            localStorage.setItem('ldr_panel_collapsed_' + panelId, isCollapsed ? 'true' : 'false');
        } catch (e) {
            SafeLogger.warn('Failed to save panel state:', e);
        }
    }

    /**
     * Dismiss a help panel permanently using the SettingsManager API
     * @param {string} panelId - The panel ID to dismiss
     */
    async function dismissPanel(panelId) {
        const settingKey = STORAGE_PREFIX + panelId;

        try {
            // Get CSRF token
            const csrfToken = window.api ? window.api.getCsrfToken() : '';

            // Save to settings via internal API (relative URL only)
            const apiUrl = SETTINGS_API_BASE + encodeURIComponent(settingKey);
            const response = await fetch(apiUrl, {
                method: 'PUT',
                headers: {
                    'Content-Type': 'application/json',
                    'X-CSRFToken': csrfToken
                },
                body: JSON.stringify({ value: true })
            });

            if (response.ok) {
                // Update cache
                dismissedCache[panelId] = true;

                // Hide the panel
                const panel = document.getElementById('help-panel-' + panelId);
                if (panel) {
                    panel.style.display = 'none';
                }

                // Show confirmation
                if (window.ui && window.ui.showMessage) {
                    window.ui.showMessage('Help panel dismissed', 'info');
                }
            } else {
                SafeLogger.error('Failed to dismiss panel:', response.status);
                if (window.ui && window.ui.showMessage) {
                    window.ui.showMessage('Failed to save preference', 'error');
                }
            }
        } catch (error) {
            SafeLogger.error('Error dismissing panel:', error);
            if (window.ui && window.ui.showMessage) {
                window.ui.showMessage('Failed to save preference', 'error');
            }
        }
    }

    /**
     * Check if a panel has been dismissed (from cache)
     * @param {string} panelId - The panel ID to check
     * @returns {boolean} - True if dismissed
     */
    function isPanelDismissed(panelId) {
        // Check cache
        if (Object.hasOwn(dismissedCache, panelId)) {
            return dismissedCache[panelId];
        }

        return false;
    }

    /**
     * Load dismissed states from backend using bulk API
     * @param {Array<string>} panelIds - List of panel IDs to check
     */
    async function loadDismissedStates(panelIds) {
        if (panelIds.length === 0) return;

        try {
            const keys = panelIds.map(id => STORAGE_PREFIX + id);
            const params = keys.map(k => 'keys[]=' + encodeURIComponent(k)).join('&');
            const response = await fetch(SETTINGS_API_BASE + 'bulk?' + params);
            if (response.ok) {
                const data = await response.json();
                if (data.success && data.settings) {
                    for (const panelId of panelIds) {
                        const setting = data.settings[STORAGE_PREFIX + panelId];
                        if (setting && (setting.value === true || setting.value === 'True' || setting.value === 'true')) {
                            dismissedCache[panelId] = true;
                        }
                    }
                }
            }
        } catch {
            // Ignore fetch errors — panels will remain visible
        }
    }

    /**
     * Initialize panel states from backend and localStorage
     */
    async function initPanelStates() {
        const panels = document.querySelectorAll('.ldr-help-panel');
        const panelIds = [];

        panels.forEach(panel => {
            const panelId = panel.getAttribute('data-panel-id');
            if (panelId) {
                panelIds.push(panelId);
            }
        });

        // Load dismissed states from backend
        await loadDismissedStates(panelIds);

        panels.forEach(panel => {
            const panelId = panel.getAttribute('data-panel-id');
            if (!panelId) return;

            // Check if panel was dismissed
            if (isPanelDismissed(panelId)) {
                panel.style.display = 'none';
                return;
            }

            // Restore collapsed state from localStorage (UI state only)
            try {
                const collapsed = localStorage.getItem('ldr_panel_collapsed_' + panelId);
                if (collapsed === 'true') {
                    panel.classList.add('collapsed');
                    const header = panel.querySelector('.ldr-help-panel-header');
                    if (header) {
                        header.setAttribute('aria-expanded', 'false');
                    }
                } else if (collapsed === 'false') {
                    panel.classList.remove('collapsed');
                    const header = panel.querySelector('.ldr-help-panel-header');
                    if (header) {
                        header.setAttribute('aria-expanded', 'true');
                    }
                }
            } catch {
                // Ignore localStorage errors
            }
        });
    }

    /**
     * Reset all dismissed panels (for testing or user request)
     */
    async function resetDismissedPanels() {
        const panels = document.querySelectorAll('.ldr-help-panel');
        let failedCount = 0;

        // Get CSRF token
        const csrfToken = window.api ? window.api.getCsrfToken() : '';

        for (const panel of panels) {
            const panelId = panel.getAttribute('data-panel-id');
            if (!panelId) continue;

            const settingKey = STORAGE_PREFIX + panelId;

            try {
                // Delete from backend
                const apiUrl = SETTINGS_API_BASE + encodeURIComponent(settingKey);
                const response = await fetch(apiUrl, {
                    method: 'DELETE',
                    headers: {
                        'X-CSRFToken': csrfToken
                    }
                });
                if (!response.ok) {
                    throw new Error(`HTTP ${response.status}`);
                }
                delete dismissedCache[panelId];
                panel.style.display = '';
            } catch (e) {
                failedCount++;
                SafeLogger.warn('Failed to reset panel dismissal:', panelId, e);
            }
        }

        if (window.ui && window.ui.showMessage) {
            if (failedCount > 0) {
                window.ui.showMessage(
                    `Could not reset ${failedCount} help panel${failedCount === 1 ? '' : 's'}`,
                    'error'
                );
            } else {
                window.ui.showMessage('Help panels reset', 'success');
            }
        }
    }

    /**
     * Expand all help panels on the page
     */
    function expandAll() {
        document.querySelectorAll('.ldr-help-panel.collapsed').forEach(panel => {
            panel.classList.remove('collapsed');
            const header = panel.querySelector('.ldr-help-panel-header');
            if (header) {
                header.setAttribute('aria-expanded', 'true');
            }
        });
    }

    /**
     * Collapse all help panels on the page
     */
    function collapseAll() {
        document.querySelectorAll('.ldr-help-panel:not(.collapsed)').forEach(panel => {
            panel.classList.add('collapsed');
            const header = panel.querySelector('.ldr-help-panel-header');
            if (header) {
                header.setAttribute('aria-expanded', 'false');
            }
        });
    }

    /**
     * Initialize the help system
     */
    async function init() {
        if (initialized) return;
        // Set the flag BEFORE awaiting so a second concurrent init() call
        // returns at the guard above instead of double-running everything.
        initialized = true;

        // Add keyboard navigation for tooltips SYNCHRONOUSLY, before the
        // awaited panel-state load below. The tooltips exist in static
        // HTML, so binding after the await left a window where Enter/Space
        // on a tooltip was lost (no handler attached yet).
        document.querySelectorAll('.ldr-help-tooltip').forEach(tooltip => {
            tooltip.addEventListener('keydown', function(e) {
                // Show tooltip on Enter or Space
                if (e.key === 'Enter' || e.key === ' ') {
                    e.preventDefault();
                    // Toggle aria-expanded for screen readers
                    const expanded = this.getAttribute('aria-expanded') === 'true';
                    this.setAttribute('aria-expanded', !expanded);
                }
            });
        });

        // Initialize panel states (async to load from backend)
        await initPanelStates();
    }

    // Auto-initialize when DOM is ready
    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', init);
    } else {
        // DOM is already ready
        init();
    }

    // Public API
    return {
        init,
        togglePanel,
        dismissPanel,
        isPanelDismissed,
        resetDismissedPanels,
        expandAll,
        collapseAll
    };
})();

// Export for global access
window.HelpService = HelpService;