documentation for all JS files

static/js/settings.js

@@ -1,3 +1,13 @@
+/**
+ * @fileoverview Manages the application settings functionality.
+ * This file handles color settings, tab persistence, and UI customization.
+ * It provides functionality to:
+ * - Manage primary and secondary color schemes
+ * - Handle settings tab navigation and persistence
+ * - Convert and manipulate colors (hex, RGB)
+ * - Update UI elements with new color schemes
+ */
+
 document.addEventListener('DOMContentLoaded', function() {
     const primaryColorInput = document.getElementById('primaryColor');
     const secondaryColorInput = document.getElementById('secondaryColor');
@@ -7,7 +17,12 @@ document.addEventListener('DOMContentLoaded', function() {
     const settingsTabs = document.querySelectorAll('#settingsTabs button[data-bs-toggle="tab"]');
     const tabContent = document.querySelectorAll('.tab-pane');
 
-    // Function to activate a specific tab
+    /**
+     * Activates a specific settings tab and updates the UI accordingly.
+     * Also persists the selected tab in localStorage.
+     * @function
+     * @param {string} tabId - The ID of the tab to activate
+     */
     function activateTab(tabId) {
         // Remove active class from all tabs and content
         settingsTabs.forEach(tab => {
@@ -42,7 +57,12 @@ document.addEventListener('DOMContentLoaded', function() {
     const savedTab = localStorage.getItem('settingsActiveTab') || window.location.hash.substring(1) || 'colors';
     activateTab(savedTab);
 
-    // Color manipulation functions
+    /**
+     * Converts a hexadecimal color code to RGB values.
+     * @function
+     * @param {string} hex - The hexadecimal color code (e.g., '#FF0000')
+     * @returns {Object|null} Object containing r, g, b values or null if invalid hex
+     */
     function hexToRgb(hex) {
         const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
         return result ? {
@@ -52,6 +72,14 @@ document.addEventListener('DOMContentLoaded', function() {
         } : null;
     }
 
+    /**
+     * Converts RGB values to a hexadecimal color code.
+     * @function
+     * @param {number} r - Red value (0-255)
+     * @param {number} g - Green value (0-255)
+     * @param {number} b - Blue value (0-255)
+     * @returns {string} Hexadecimal color code
+     */
     function rgbToHex(r, g, b) {
         return '#' + [r, g, b].map(x => {
             const hex = x.toString(16);
@@ -59,6 +87,13 @@ document.addEventListener('DOMContentLoaded', function() {
         }).join('');
     }
 
+    /**
+     * Lightens a color by a specified amount.
+     * @function
+     * @param {string} color - The hexadecimal color to lighten
+     * @param {number} amount - The amount to lighten (0-1)
+     * @returns {string} The lightened hexadecimal color
+     */
     function lightenColor(color, amount) {
         const rgb = hexToRgb(color);
         if (!rgb) return color;
@@ -70,6 +105,13 @@ document.addEventListener('DOMContentLoaded', function() {
         );
     }
 
+    /**
+     * Darkens a color by a specified amount.
+     * @function
+     * @param {string} color - The hexadecimal color to darken
+     * @param {number} amount - The amount to darken (0-1)
+     * @returns {string} The darkened hexadecimal color
+     */
     function darkenColor(color, amount) {
         const rgb = hexToRgb(color);
         if (!rgb) return color;
@@ -81,6 +123,13 @@ document.addEventListener('DOMContentLoaded', function() {
         );
     }
 
+    /**
+     * Updates all color-related UI elements based on a new color value.
+     * Updates CSS variables, chart colors, and color previews.
+     * @function
+     * @param {string} color - The new color value in hexadecimal
+     * @param {boolean} isPrimary - Whether this is the primary color (true) or secondary color (false)
+     */
     function updateAllColors(color, isPrimary) {
         const prefix = isPrimary ? 'primary' : 'secondary';
         
@@ -162,7 +211,11 @@ document.addEventListener('DOMContentLoaded', function() {
         updateAllColors(secondaryColorInput.value, false);
     });
 
-    // Initialize colors from database values
+    /**
+     * Initializes the color settings from the current CSS variables.
+     * Updates input values and color previews.
+     * @function
+     */
     function initializeColors() {
         // Get the current computed CSS variable values
         const computedPrimaryColor = getComputedStyle(document.documentElement).getPropertyValue('--primary-color').trim();