Patchwork PR: GenerateReadme

README.md

@@ -1,81 +1,84 @@
-# 🎨 VSCode Theme Generator
-
-Generate stunning, customized VSCode themes with our intelligent color algorithm and semantic token system.
-
-## ✨ Features
-
-- 🖌️ Intelligent color generation algorithm
-- 🧠 Semantic token support for enhanced syntax highlighting
-- 🎭 Light and dark theme variants
-- 🔧 Customizable color palettes
-- 📦 Easy export to VSCode extension format
-
-## 🧬 Color Generation Algorithm
-
-Our algorithm creates harmonious color schemes by:
-
-1. Selecting a base color
-2. Generating complementary and analogous colors
-3. Adjusting saturation and brightness for optimal contrast
-4. Applying color theory principles for visual appeal
-
-## 🏷️ Semantic Tokens
-
-We use semantic tokens to provide consistent and meaningful syntax highlighting:
-
-- `keyword`: Language keywords
-- `string`: String literals
-- `comment`: Comments
-- `function`: Function declarations and calls
-- `variable`: Local variables
-- `type`: Type annotations
-- `constant`: Constant values
-- `class`: Class declarations
-- `number`: Numeric literals
-- `operator`: Operators
-- `parameter`: Function parameters
-- `property`: Object properties
-- `punctuation`: Punctuation marks
-- `selector`: Selectors in CSS/SCSS
-- `storage`: Storage keywords
-- `support`: Support functions and classes
-- `modifier`: Modifiers and access specifiers
-- `control`: Control flow keywords
-- `decorator`: Decorators and annotations
-- `tag`: HTML/XML tags
-- `attribute`: HTML/XML attributes
-- `namespace`: Namespaces and packages
-- `regex`: Regular expressions
-- `escape`: Escape characters
-- `metaBrace`: Meta braces and brackets
-- `docKeyword`: Documentation keywords
-- `heading`: Markdown headings
-- `link`: Hyperlinks
-- `list`: List items
-- `quote`: Quotations
-- `raw`: Raw text blocks
-
-These tokens ensure a rich and nuanced syntax highlighting experience across various programming languages and file types.
-
-## 🤝 How to Contribute
-
-1. Fork the repository
-2. Create a new branch: `git checkout -b feature/your-feature-name`
-3. Make your changes and commit: `git commit -m "Add your feature"`
-4. Push to your fork: `git push origin feature/your-feature-name`
-5. Create a pull request
-
-## 🚀 Future Improvements
-
-- [ ] Improve Monaco editor preview to reflect VSCode themes with higher fidelity
-- [ ] Implement language-specific semantic tokens
-- [ ] Add support for popular frameworks (React, Vue, Angular)
-- [ ] Create theme templates for different coding styles
-- [ ] Improve accessibility options for color-blind users
-- [ ] Develop a web-based theme preview and customization tool
-
-We welcome contributions and ideas to make this theme generator even better!
-
-## 📄 License
-
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+# VS Code Theme Generator Documentation
+
+## Overview
+
+This project is a VS Code Theme Generator that allows users to create custom color themes for Visual Studio Code. It provides a user-friendly interface for adjusting various color settings and previewing the results in real-time.
+
+## Key Components
+
+### ThemeContext (src/contexts/ThemeContext.tsx)
+
+The ThemeContext is the core of the application, managing the state and providing theme-related functions to all components. It uses React's Context API to share theme data and functions across the component tree.
+
+Key features:
+- Manages theme state (isDark, baseHue, uiSaturation, syntaxSaturation, scheme)
+- Provides functions for generating and updating colors
+- Handles color locking and active color selection
+
+### ThemeControls (src/components/ThemeControls.tsx)
+
+This component provides the user interface for adjusting theme settings. It includes controls for:
+- Toggling dark/light mode
+- Selecting color scheme
+- Adjusting base hue, UI saturation, and syntax saturation
+- Randomizing colors
+- Regenerating ANSI colors
+
+### ColorList (src/components/ColorList.tsx)
+
+Displays a list of theme colors or syntax colors, allowing users to:
+- View current color values
+- Lock/unlock individual colors
+- Copy color values to clipboard
+- Select a color for editing
+
+### ActiveColorPicker (src/components/ActiveColorPicker.tsx)
+
+Provides a color picker for editing the currently selected color.
+
+### ThemePreview (src/components/ThemePreview.tsx)
+
+Renders a preview of the generated theme, including:
+- A mock VS Code interface
+- Syntax-highlighted code samples in various languages
+- Real-time updates as theme settings are changed
+
+### ExportButton (src/components/ExportButton.tsx)
+
+Allows users to export the generated theme as a JSON file compatible with VS Code.
+
+## Color Generation
+
+The color generation process is handled by utility functions in:
+- src/lib/utils/colorUtils.ts
+- src/lib/utils/themeColors.ts
+- src/lib/utils/syntaxColors.ts
+- src/lib/utils/ansiColors.ts
+
+These functions generate harmonious color schemes based on user inputs and ensure proper contrast and readability.
+
+## Inputs
+
+- Dark/Light mode toggle
+- Base hue (0-359)
+- UI Saturation (0-100)
+- Syntax Saturation (0-100)
+- Color Scheme selection
+- Individual color adjustments
+
+## Outputs
+
+- A complete set of theme colors for VS Code
+- Syntax highlighting colors
+- ANSI terminal colors
+- Exportable theme JSON file
+
+## Usage
+
+1. Adjust theme controls to customize colors
+2. Preview changes in real-time
+3. Fine-tune individual colors if needed
+4. Export the theme for use in VS Code
+
+This application provides a powerful and intuitive way for developers to create custom VS Code themes tailored to their preferences.

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) {