Merge pull request #1 from RodrigoLuglio/patchwork-generatedocstring-…

…main

Patchwork PR: GenerateDocstring

src/contexts/ThemeContext.tsx

@@ -133,6 +133,12 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
             extendedSchemeHues,
             fullOptions.syntaxSaturation,
             Object.fromEntries(
+              /**
+               * Filters the entries of syntaxColors object based on locked color keys
+               * @param {Object} syntaxColors - An object containing syntax highlighting color configurations
+               * @param {Set} lockedColorSet - A Set containing keys of locked colors
+               * @returns {Array} An array of key-value pairs for locked syntax colors
+               */
               Object.entries(syntaxColors).filter(([key]) =>
                 lockedColorSet.has(key)
               )
@@ -160,6 +166,11 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     ]
   );
 
+  /**
+   * Updates the dark mode state and generates corresponding colors
+   * @param {boolean} value - The new dark mode state (true for dark mode, false for light mode)
+   * @returns {void} This function doesn't return a value
+   */
   const setIsDark = useCallback(
     (value: boolean) => {
       setIsDarkState(value);
@@ -168,6 +179,11 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [generateColors]
   );
 
+  /**
+   * Updates the base hue state and generates new colors based on the provided value.
+   * @param {number} value - The new base hue value to set.
+   * @returns {void} This function doesn't return a value.
+   */
   const setBaseHue = useCallback(
     (value: number) => {
       setBaseHueState(value);
@@ -176,6 +192,12 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [generateColors]
   );
 
+  /**
+   * Updates the theme and syntax colors with new saturation values
+   * @param {number} newUiSaturation - The new saturation value for UI colors
+   * @param {number} newSyntaxSaturation - The new saturation value for syntax colors
+   * @returns {void} This function doesn't return a value, it updates state
+   */
   const updateColorsWithSaturation = useCallback(
     (newUiSaturation: number, newSyntaxSaturation: number) => {
       const newColors = updateThemeColorsWithSaturation(
@@ -197,6 +219,11 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [colors, syntaxColors, lockedColors]
   );
 
+  /**
+   * Updates the UI saturation state and applies the new saturation value to colors.
+   * @param {number} value - The new saturation value to be set.
+   * @returns {void} This function doesn't return a value.
+   */
   const setUiSaturation = useCallback(
     (value: number) => {
       setUiSaturationState(value);
@@ -205,6 +232,11 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [syntaxSaturation, updateColorsWithSaturation]
   );
 
+  /**
+   * Updates the syntax saturation state and refreshes colors with the new saturation value.
+   * @param {number} value - The new saturation value to be applied.
+   * @returns {void} This function doesn't return a value.
+  */
   const setSyntaxSaturation = useCallback(
     (value: number) => {
       setSyntaxSaturationState(value);
@@ -213,6 +245,11 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [uiSaturation, updateColorsWithSaturation]
   );
 
+  /**
+   * Updates the color scheme and generates new colors based on the selected scheme.
+   * @param {ColorScheme} value - The new color scheme to be applied.
+   * @returns {void} This function doesn't return a value.
+   */
   const setScheme = useCallback(
     (value: ColorScheme) => {
       setSchemeState(value);
@@ -221,7 +258,18 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [generateColors]
   );
 
+  /**
+   * Toggles the lock state of a color in the color palette.
+   * @param {string} colorKey - The key of the color to toggle the lock state for.
+   * @returns {void} This function doesn't return a value, it updates the state internally.
+   */
   const toggleColorLock = useCallback((colorKey: string) => {
+    /**
+     * Toggles the locked state of a color in the set of locked colors
+     * @param {function} prev - The previous state of the locked colors set
+     * @param {string} colorKey - The key of the color to toggle
+     * @returns {Set} A new Set with the updated locked colors
+     */
     setLockedColors((prev) => {
       const newSet = new Set(prev);
       if (newSet.has(colorKey)) {
@@ -233,25 +281,51 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     });
   }, []);
 
+  /**
+   * Updates color values based on the provided color key and new color.
+   * @param {string} colorKey - The key identifying which color to update (e.g., "ansi", "BG1", or syntax color keys).
+   * @param {string} newColor - The new color value to set.
+   * @returns {void} This function doesn't return a value, it updates state.
+   */
   const handleColorChange = useCallback(
     (colorKey: string, newColor: string) => {
       if (colorKey.startsWith("ansi")) {
+        /**
+         * Updates a specific ANSI color in the state
+         * @param {function} prevColors - A function that receives the previous state of colors
+         * @returns {object} An updated object containing the new color for the specified key
+         */
         setAnsiColors((prevColors) => ({
           ...prevColors,
           [colorKey.slice(4)]: newColor,
         }));
       } else if (colorKey in colors) {
+        /**
+         * Updates a specific color in the colors state object
+         * @param {function} prevColors - Callback function that receives the previous colors state
+         * @returns {object} Updated colors state object with the new color value for the specified key
+         */
         setColors((prevColors) => ({
           ...prevColors,
           [colorKey]: newColor,
         }));
         if (colorKey === "BG1") {
+          /**
+           * Updates the syntax colors based on a new color and existing scheme parameters
+           * @param {function} prevSyntaxColors - Callback function to access the previous syntax colors state
+           * @returns {object} Updated syntax colors object
+           */
           setSyntaxColors((prevSyntaxColors) => ({
             ...prevSyntaxColors,
             ...generateSyntaxColors(newColor, schemeHues, syntaxSaturation),
           }));
         }
       } else if (colorKey in syntaxColors) {
+        /**
+         * Updates the syntax colors by setting a new color for a specific color key
+         * @param {function} prevSyntaxColors - A function that returns the previous syntax colors object
+         * @returns {object} An updated syntax colors object with the new color applied to the specified color key
+         */
         setSyntaxColors((prevSyntaxColors) => ({
           ...prevSyntaxColors,
           [colorKey]: newColor,
@@ -261,10 +335,20 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
     [colors, syntaxColors, schemeHues, syntaxSaturation]
   );
 
+  /**
+   * Regenerates ANSI colors based on the current background color.
+   * @param {void} - This function doesn't take any parameters.
+   * @returns {void} This function doesn't return a value, but updates the state with new ANSI colors.
+   */
   const regenerateAnsiColors = useCallback(() => {
     setAnsiColors(generateAnsiColors(colors.BG1));
   }, [colors.BG1]);
-
+  /**
+   * A React effect hook that regenerates ANSI colors when specific dependencies change.
+   * @param {Function} regenerateAnsiColors - Function to regenerate ANSI colors.
+   * @param {string} colors.BG1 - The background color that triggers regeneration when changed.
+   * @returns {void} This effect does not return anything.
+   */
   useEffect(() => {
     regenerateAnsiColors();
   }, [colors.BG1, regenerateAnsiColors]);
@@ -299,6 +383,11 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({
   );
 };
 
+/**
+ * A custom hook to access the current theme context
+ * @returns {Object} The current theme context
+ * @throws {Error} If used outside of a ThemeProvider
+ */
 export const useTheme = () => {
   const context = useContext(ThemeContext);
   if (context === undefined) {

src/lib/utils/ansiColors.ts

@@ -20,10 +20,21 @@ export interface AnsiColors {
   BrightWhite: string;
 }
 
+/**
+ * Generates a set of ANSI colors based on a given background color.
+ * @param {string} backgroundColor - The background color to base the generated colors on.
+ * @returns {AnsiColors} An object containing generated ANSI colors with enhanced readability.
+ */
 export function generateAnsiColors(backgroundColor: string): AnsiColors {
   const baseSaturation = 20 + Math.random() * 60; // 20-80
   const baseLightness = 30 + Math.random() * 30; // 30-60
 
+  /**
+   * Generates a color based on the given parameters.
+   * @param {number} baseHue - The base hue value to start from (0-360).
+   * @param {boolean} [isGrayscale=false] - Whether to generate a grayscale color.
+   * @returns {string} A hexadecimal color string.
+   */
   const generateColor = (baseHue: number, isGrayscale: boolean = false) => {
     if (isGrayscale) {
       return Color.hsl(0, 0, baseLightness).hex();
@@ -40,6 +51,11 @@ export function generateAnsiColors(backgroundColor: string): AnsiColors {
     return Color.hsl(hue, saturation, lightness).hex();
   };
 
+  /**
+   * Brightens a given color by increasing its saturation and lightness.
+   * @param {string} color - The input color in any valid CSS color format.
+   * @returns {string} A new color in hexadecimal format with increased brightness.
+   */
   const brightenColor = (color: string) => {
     const c = Color(color);
     const brightSaturation = Math.min(
@@ -53,6 +69,12 @@ export function generateAnsiColors(backgroundColor: string): AnsiColors {
     return c.saturationl(brightSaturation).lightness(brightLightness).hex();
   };
 
+  /**
+   * Ensures the readability of a color against a background color, except for black.
+   * @param {string} color - The foreground color to check and potentially adjust.
+   * @param {string} bgColor - The background color to check against.
+   * @returns {string} The original color if it's black, otherwise a color with sufficient contrast against the background.
+   */
   const ensureReadabilityExceptBlack = (color: string, bgColor: string) => {
     if (color.toLowerCase() === "#000000") return color;
     return ensureReadability(color, bgColor, 4.5);