📝 docs: enhance code documentation

- Add JSDoc documentation to all components and utilities - Document event system and data flows - Add module descriptions to all files - Standardize event documentation format - Complete event flow documentation - Add type definitions and examples
SylvieCanongia · Dec 4, 2024 · 3f5ca27 · 3f5ca27
1 parent b98042b
commit 3f5ca27
Show file tree

Hide file tree

Showing 15 changed files with 342 additions and 48 deletions.
diff --git a/src/js/components/colorInput.js b/src/js/components/colorInput.js
@@ -9,7 +9,15 @@
  */
 
 // src/js/components/colorInput.js
-import { eventBus } from "../utils/eventBus.js";
+
+/**
+ * Color input handling and validation
+ * @module components/colorInput
+ * @description Manages color input fields, format detection, and validation
+ */
+
+/** @typedef {import('../utils/colorStore.js').ColorStore} ColorStore */
+
 import { isValidHSL, isValidRGB, isValidHEX, detectColorFormat, validateDetailedInput } from "../utils/validation.js";
 import { rgbToHsl, hexToHsl } from "../utils/colorUtils.js";
 import { resetPalettes } from "./palette.js";
@@ -21,23 +29,38 @@ const TYPES = {
   ACCENT: "accent",
 };
 
+/**
+ * Initializes color input handling for all color types (primary, secondary, accent)
+ * @param {ColorStore} colorStore - Color store instance for state
+ */
 export const initColorInputs = (colorStore) => {
-  // Initialize input handling for a specific color type
+  /**
+   * Sets up HSL input handling for a specific color type
+   * @param {string} type - Color type (primary/secondary/accent)
+   */
   const setupHSLInput = (type) => {
     const hslInput = document.getElementById(`${type}HslInput`);
     const errorElement = document.getElementById(`${type}HslError`);
     const hueInput = document.getElementById(`${type}-hue`);
     const saturationInput = document.getElementById(`${type}-saturation`);
     const lightnessInput = document.getElementById(`${type}-lightness`);
 
-    // Update detailed inputs with HSL values
+    /**
+     * Updates detailed input fields with HSL values
+     * @param {Object} hsl - HSL color object
+     * @param {number} hsl.hue - Hue value (0-360)
+     * @param {number} hsl.saturation - Saturation value (0-100)
+     * @param {number} hsl.lightness - Lightness value (0-100)
+     */
     const updateDetailedInputs = (hsl) => {
       hueInput.value = hsl.hue;
       saturationInput.value = hsl.saturation;
       lightnessInput.value = hsl.lightness;
     };
 
-    // Clear all inputs and reset palettes
+    /**
+     * Clears all input fields and resets palettes
+     */
     const clearInputs = () => {
       hslInput.value = "";
       hueInput.value = "";
@@ -48,7 +71,10 @@ export const initColorInputs = (colorStore) => {
       resetPalettes(type); // Reset palettes when inputs are cleared
     };
 
-    // Handle HSL input changes
+    /**
+     * Handles changes in the HSL input field
+     * Validates input format and updates color state
+     */
     const handleHSLInput = () => {
       const value = hslInput.value.trim();
       const detailedInputs = [hueInput, saturationInput, lightnessInput];
@@ -138,7 +164,11 @@ export const initColorInputs = (colorStore) => {
       colorStore.updateColor(type, hslValues);
     };
 
-    // Handle detailed inputs changes
+    /**
+     * Handles changes in detailed HSL input fields
+     * Validates input values and updates color state
+     * @param {Event} event - Input event object
+     */
     const handleDetailedInput = (event) => {
       const input = event.target;
       const min = parseInt(input.min);

diff --git a/src/js/components/helpGuide.js b/src/js/components/helpGuide.js
@@ -9,13 +9,30 @@
  */
 
 // src/js/components/helpGuide.js
+
+/**
+ * Help guide dialog component
+ * @module components/helpGuide
+ * @description Manages bilingual help guide modal with theme support
+ */
+
 import { eventBus } from "../utils/eventBus.js";
 import { guideContent } from "../utils/guideContent.js";
 
 /**
- * Renders different types of content sections
+ * Helper functions for rendering different types of content sections
+ * @namespace renderHelpers
  */
 const renderHelpers = {
+  /**
+   * Renders a list of color formats with examples
+   * @param {Object} formats - Format information
+   * @param {string} formats.title - Section title
+   * @param {Array<Object>} formats.formats - List of formats
+   * @param {string} formats.formats[].type - Format type
+   * @param {string} formats.formats[].example - Format example
+   * @returns {string} HTML string for formats section
+   */
   renderFormats: (formats) => `
     <div class="format-list">
       <h4>${formats.title}</h4>
@@ -34,6 +51,15 @@ const renderHelpers = {
     </div>
   `,
 
+  /**
+   * Renders a list of color variations
+   * @param {Object} variations - Variation information
+   * @param {string} variations.title - Section title
+   * @param {Array<Object>} variations.variations - List of variations
+   * @param {string} variations.variations[].type - Variation type
+   * @param {string} variations.variations[].description - Variation description
+   * @returns {string} HTML string for variations section
+   */
   renderVariations: (variations) => `
     <div class="variations-list">
       <h4>${variations.title}</h4>
@@ -51,6 +77,15 @@ const renderHelpers = {
     </div>
   `,
 
+  /**
+   * Renders a list of features
+   * @param {Object} features - Feature information
+   * @param {string} features.title - Section title
+   * @param {Array<Object>} features.features - List of features
+   * @param {string} features.features[].action - Feature action
+   * @param {string} features.features[].description - Feature description
+   * @returns {string} HTML string for features section
+   */
   renderFeatures: (features) => `
     <div class="features-list">
       <h4>${features.title}</h4>
@@ -68,6 +103,15 @@ const renderHelpers = {
     </div>
   `,
 
+  /**
+   * Renders a list of guidelines
+   * @param {Object} guidelines - Guideline information
+   * @param {string} guidelines.title - Section title
+   * @param {Array<Object>} guidelines.guidelines - List of guidelines
+   * @param {string} guidelines.guidelines[].rule - Guideline rule
+   * @param {string} guidelines.guidelines[].value - Guideline value
+   * @returns {string} HTML string for guidelines section
+   */
   renderGuidelines: (guidelines) => `
     <div class="guidelines-list">
       <h4>${guidelines.title}</h4>
@@ -122,6 +166,11 @@ const renderSection = (section) => {
 
 /**
  * Initializes the help guide functionality
+ * @listens {themeChanged} Updates guide theme
+ * @emits {guideOpened} When guide opens
+ * @emits {guideClosed} When guide closes
+ * @emits {languageChanged} { lang } When language changes
+ * @emits {guideContentUpdated} { lang } When guide content is updated
  */
 export const initHelpGuide = () => {
   // Cache DOM elements

diff --git a/src/js/components/palette.js b/src/js/components/palette.js
@@ -9,6 +9,15 @@
  */
 
 // src/js/components/palette.js
+
+/**
+ * Palette generation and management
+ * @module components/palette
+ * @description Handles color palette generation, display and interactions
+ */
+
+/** @typedef {import('../utils/colorStore.js').ColorStore} ColorStore */
+
 import { eventBus } from "../utils/eventBus.js";
 import { createHSLString, createColorString, generatePaletteWithConfig, generatePaletteVariations } from "../utils/colorUtils.js";
 import { generateVariableName, getCurrentPrefix } from "../utils/cssVarPrefix.js";
@@ -126,7 +135,9 @@ export const resetPalettes = (type) => {
 
 /**
  * Initializes all color palettes (Normal and Vivid variants)
- * @param {Object} colorStore - Color store instance
+ * @param {ColorStore} colorStore - Color store instance for state
+ * @listens {colorUpdate} Updates palettes when color changes
+ * @listens {formatUpdate} Updates color format in palettes
  * @returns {void}
  */
 export const initPalettes = (colorStore) => {
@@ -176,7 +187,8 @@ export const initPalettes = (colorStore) => {
 
 /**
  * Initializes export functionality for all palettes
- * @param {Object} colorStore - Color store instance
+ * @param {ColorStore} colorStore - Color store instance for state
+ * @returns {void}
  */
 export const initExportAllPalettes = (colorStore) => {
   const exportButton = document.getElementById("exportAllPalettes");
@@ -238,8 +250,7 @@ export const initExportAllPalettes = (colorStore) => {
 };
 
 /**
- * Copies all generated palettes in selected format (HSL, RGB, HEX)
- * @param {Object} colorStore - Color store instance
+ * Initializes copy functionality for all palettes
  * @returns {void}
  */
 export const initCopyAllPalettes = () => {

diff --git a/src/js/components/preview.js b/src/js/components/preview.js
@@ -9,11 +9,19 @@
  */
 
 // src/js/components/preview.js
+
+/**
+ * Color preview component
+ * @module components/preview
+ * @description Handles real-time color preview display and updates
+ */
+
 import { eventBus } from "../utils/eventBus.js";
 import { createHSLString } from "../utils/colorUtils.js";
 
 /**
  * Initialize preview component
+ * @listens {colorUpdate} Updates preview display when color changes
  */
 export const initPreview = () => {
   // Subscribe to color updates

diff --git a/src/js/components/tabs.js b/src/js/components/tabs.js
@@ -9,6 +9,13 @@
  */
 
 // src/js/components/tabs.js
+
+/**
+ * Tab navigation system
+ * @module components/tabs
+ * @description Manages color type tabs and panel switching
+ */
+
 import { eventBus } from "../utils/eventBus.js";
 
 /**
@@ -32,6 +39,7 @@ export const initTabs = () => {
   /**
    * Switches active tab and panel
    * @param {HTMLElement} selectedTab - The tab to activate
+   * @emits {tabChange} { colorType } When active tab changes
    */
   const switchTab = (selectedTab) => {
     const colorType = selectedTab.getAttribute("data-color-type");

diff --git a/src/js/main.js b/src/js/main.js
@@ -9,7 +9,13 @@
  */
 
 // src/js/main.js
-import { eventBus } from "./utils/eventBus.js";
+
+/**
+ * Main application entry point
+ * @module main
+ * @description Initializes the application components and state management
+ */
+
 import { createColorStore } from "./utils/colorStore.js";
 import { initTabs } from "./components/tabs.js";
 import { initColorInputs } from "./components/colorInput.js";
@@ -19,10 +25,21 @@ import { initHelpGuide } from "./components/helpGuide.js";
 import { initCssVarPrefix } from "./utils/cssVarPrefix.js";
 import { initPreview } from "./components/preview.js";
 
-// Create store instance
+/**
+ * Global color store instance
+ * @type {Object}
+ */
 let colorStore;
 
-// Wait for all resources to load
+/**
+ * Initializes the application
+ * Follows a specific order to ensure proper component dependencies:
+ * 1. Core utilities (colorStore)
+ * 2. UI components (tabs, inputs, palettes)
+ * 3. Theme and guide features
+ * 
+ * @throws {Error} When initialization fails
+ */
 window.addEventListener("load", () => {
   try {
     // Initialize core utilities
@@ -44,7 +61,10 @@ window.addEventListener("load", () => {
   } catch (error) {
     console.error("Failed to initialize application:", error);
 
-    // Display user-friendly error message if needed
+    /**
+     * Display user-friendly error message
+     * @param {string} message - Error message to display
+     */
     const container = document.querySelector(".container");
     if (container) {
       const errorMessage = document.createElement("div");

diff --git a/src/js/utils/colorStore.js b/src/js/utils/colorStore.js
@@ -8,12 +8,34 @@
  * (at your option) any later version.
  */
 
+// src/js/utils/colorStore.js
+
 /**
  * Color store module for managing application color state
  * @module colorStore
  */
+
+/**
+ * @typedef {Object} HSLColor
+ * @property {number} hue - Hue value (0-360)
+ * @property {number} saturation - Saturation value (0-100)
+ * @property {number} lightness - Lightness value (0-100)
+ */
+
+/**
+ * @typedef {Object} ColorStore
+ * @property {function(string, Object|null): void} updateColor - Updates color in store
+ * @property {function(string): Object|null} getColor - Gets current color from store
+ * @property {function(string): void} updateFormat - Updates color format
+ * @property {function(): string} getFormat - Gets current color format
+ */
+
 import { eventBus } from "./eventBus.js";
 
+/**
+ * Creates a color store instance
+ * @returns {ColorStore} Color store instance
+ */
 export const createColorStore = () => {
   const state = {
     primary: null,
@@ -24,9 +46,13 @@ export const createColorStore = () => {
   };
 
   /**
-   * Update color in store
-   * @param {string} type - Color type (primary/secondary/accent)
-   * @param {string} color - Color value
+   * Update color in store and notify subscribers
+ * @param {string} type - Color type (primary/secondary/accent)
+ * @param {Object|null} color - HSL color object or null
+ * @param {number} color.hue - Hue value (0-360)
+ * @param {number} color.saturation - Saturation value (0-100)
+ * @param {number} color.lightness - Lightness value (0-100)
+ * @emits {colorUpdate} { type, color } - Color update event
    */
   const updateColor = (type, color) => {
     state[type] = color;
@@ -36,13 +62,14 @@ export const createColorStore = () => {
   /**
    * Get current color state
    * @param {string} type - Color type
-   * @returns {string|null} Color value
+   * @returns {HSLColor|null} Current color object or null
    */
   const getColor = (type) => state[type];
 
   /**
-   * Update format preference
+   * Update format preference and notify subscribers
    * @param {string} format - Color format (hex/rgb/hsl)
+   * @emits {formatUpdate} format - New color format
    */
   const updateFormat = (format) => {
     state.format = format;

diff --git a/src/js/utils/colorUtils.js b/src/js/utils/colorUtils.js
@@ -10,6 +10,12 @@
 
 // src/js/utils/colorUtils.js
 
+/**
+ * Color manipulation utilities
+ * @module utils/colorUtils
+ * @description Provides color conversion, palette generation and color calculations
+ */
+
 /**
  * Creates an HSL color string from component values
  * @param {Object} params - HSL color components