@codeleap/styles 5.8.2 → 5.8.3

package/src/theme/tests/validateTheme.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from 'bun:test'
+import { validateTheme } from '../validateTheme'
+
+describe('validateTheme', () => {
+  test('should merge baseColors into colors', () => {
+    const theme: any = {
+      baseColors: {
+        primary: '#000000',
+        secondary: '#ffffff',
+      },
+      colors: {
+        background: '#f0f0f0',
+        text: '#333333',
+      },
+    }
+
+    const result = validateTheme(theme)
+
+    expect(result.colors).toEqual({
+      primary: '#000000',
+      secondary: '#ffffff',
+      background: '#f0f0f0',
+      text: '#333333',
+    })
+  })
+
+  test('should validate and merge alternate color schemes', () => {
+    const theme: any = {
+      baseColors: {
+        primary: '#000000',
+        secondary: '#ffffff',
+      },
+      colors: {
+        background: '#f0f0f0',
+        text: '#333333',
+      },
+      alternateColors: {
+        dark: {
+          background: '#1a1a1a',
+          text: '#ffffff',
+        },
+      },
+    }
+
+    const result = validateTheme(theme)
+
+    expect(result.alternateColors.dark).toEqual({
+      primary: '#000000',
+      secondary: '#ffffff',
+      background: '#1a1a1a',
+      text: '#ffffff',
+    })
+  })
+
+  test('should throw error when alternate scheme is missing required colors', () => {
+    const theme: any = {
+      baseColors: {
+        primary: '#000000',
+      },
+      colors: {
+        background: '#f0f0f0',
+        text: '#333333',
+      },
+      alternateColors: {
+        dark: {
+          background: '#1a1a1a',
+          // Missing 'text' color
+        },
+      },
+    }
+
+    expect(() => validateTheme(theme)).toThrow(
+      'Alternate color scheme dark is missing color text'
+    )
+  })
+
+  test('should handle theme without alternateColors', () => {
+    const theme: any = {
+      baseColors: {
+        primary: '#000000',
+      },
+      colors: {
+        background: '#f0f0f0',
+      },
+    }
+
+    const result = validateTheme(theme)
+
+    expect(result.colors).toEqual({
+      primary: '#000000',
+      background: '#f0f0f0',
+    })
+    expect(result.alternateColors).toEqual({})
+  })
+
+  test('should handle empty baseColors', () => {
+    const theme: any = {
+      baseColors: {},
+      colors: {
+        background: '#f0f0f0',
+        text: '#333333',
+      },
+      alternateColors: {
+        dark: {
+          background: '#1a1a1a',
+          text: '#ffffff',
+        },
+      },
+    }
+
+    const result = validateTheme(theme)
+
+    expect(result.colors).toEqual({
+      background: '#f0f0f0',
+      text: '#333333',
+    })
+    expect(result.alternateColors.dark).toEqual({
+      background: '#1a1a1a',
+      text: '#ffffff',
+    })
+  })
+
+  test('should handle multiple alternate color schemes', () => {
+    const theme: any = {
+      baseColors: {
+        primary: '#000000',
+      },
+      colors: {
+        background: '#f0f0f0',
+        text: '#333333',
+      },
+      alternateColors: {
+        dark: {
+          background: '#1a1a1a',
+          text: '#ffffff',
+        },
+        light: {
+          background: '#ffffff',
+          text: '#000000',
+        },
+      },
+    }
+
+    const result = validateTheme(theme)
+
+    expect(Object.keys(result.alternateColors)).toEqual(['dark', 'light'])
+    expect(result.alternateColors.dark).toEqual({
+      primary: '#000000',
+      background: '#1a1a1a',
+      text: '#ffffff',
+    })
+    expect(result.alternateColors.light).toEqual({
+      primary: '#000000',
+      background: '#ffffff',
+      text: '#000000',
+    })
+  })
+
+  test('should preserve all original theme properties', () => {
+    const theme: any = {
+      baseColors: { primary: '#000000' },
+      colors: { background: '#f0f0f0' },
+      alternateColors: { dark: { background: '#1a1a1a' } },
+      name: 'test-theme',
+      fontSize: { sm: '12px', md: '16px' },
+    }
+
+    const result = validateTheme(theme)
+
+    expect(result.name).toBe('test-theme')
+    expect(result.fontSize).toEqual({ sm: '12px', md: '16px' })
+  })
+})

package/src/{lib → theme}/themeStore.ts

@@ -1,12 +1,19 @@
 import { AppTheme, ColorMap, IAppVariants, ITheme, Theme } from '../types'
 import { map, computed, atom } from 'nanostores'
 
+/**
+ * Theme state interface containing theme and color scheme information.
+ */
 export type ThemeState = {
   theme: AppTheme<Theme> | null
   colorScheme: string | null
 }
 
-class ThemeStore {
+/**
+ * Global theme store that manages application theme, color schemes, and variants.
+ * Uses nanostores for reactive state management.
+ */
+export class ThemeStore {
   private readonly alternateColorsSchemeStore = map<{ [key: string]: ColorMap }>({})
 
   public readonly colorSchemeStore = atom<string | null>(null)
@@ -15,44 +22,84 @@ class ThemeStore {
 
   public readonly variantsStore = map<IAppVariants>({})
 
+  /**
+   * Gets the current theme.
+   * @returns {ITheme | null} Current theme or null if not set
+   */
   get theme() {
     return this.themeStore.get()
   }
 
+  /**
+   * Gets the current theme with typed interface.
+   * @returns {AppTheme<Theme>} Current theme cast to AppTheme type
+   */
   get themeTyped() {
     return this.themeStore.get() as unknown as AppTheme<Theme>
   }
 
+  /**
+   * Gets the current color scheme name.
+   * @returns {string | null} Current color scheme name or null if not set
+   */
   get colorScheme() {
     return this.colorSchemeStore.get()
   }
 
+  /**
+   * Gets the current variants configuration.
+   * @returns {IAppVariants} Current variants object
+   */
   get variants() {
     return this.variantsStore.get()
   }
 
+  /**
+   * Gets all alternate color schemes.
+   * @returns {{ [key: string]: ColorMap }} Object containing all alternate color schemes
+   */
   get alternateColorsScheme() {
     return this.alternateColorsSchemeStore.get() ?? {}
   }
 
+  /**
+   * Sets the variants configuration.
+   * @template T
+   * @param {T} variants - Variants configuration to set
+   */
   setVariants<T>(variants: T) {
     this.variantsStore.set(variants as unknown as IAppVariants)
   }
 
+  /**
+   * Sets the current color scheme.
+   * @param {string} colorScheme - Color scheme name to set
+   */
   setColorScheme(colorScheme: string) {
     this.colorSchemeStore.set(colorScheme)
   }
 
+  /**
+   * Sets the current theme.
+   * @param {ITheme} theme - Theme object to set
+   */
   setTheme(theme: ITheme) {
     this.themeStore.set(theme)
   }
 
+  /**
+   * Sets all alternate color schemes.
+   * @param {{ [key: string]: ColorMap }} colors - Object containing color schemes
+   */
   setAlternateColorsScheme(colors: { [key: string]: ColorMap }) {
     this.alternateColorsSchemeStore.set(colors)
   }
 
-  // utils
-
+  /**
+   * Gets the base color scheme colors (first available scheme).
+   * @private
+   * @returns {ColorMap} Base color scheme colors
+   */
   private getBaseSchemeColors(): ColorMap {
     const alternateColors = this.alternateColorsScheme ?? {}
     const colorSchemeKeys = Object.keys(alternateColors)
@@ -64,6 +111,12 @@ class ThemeStore {
     return alternateColors[colorSchemeKeys[0]] ?? {}
   }
 
+  /**
+   * Injects a new color scheme, merging with base scheme colors.
+   * @param {string} name - Name of the color scheme
+   * @param {ColorMap} colors - Color map to inject
+   * @returns {{ [key: string]: ColorMap }} Updated alternate colors object
+   */
   injectColorScheme(name: string, colors: ColorMap) {
     const baseSchemeColors = this.getBaseSchemeColors()
     const currentAlternateColors = this.alternateColorsScheme ?? {}
@@ -82,6 +135,11 @@ class ThemeStore {
     return alternateColors
   }
 
+  /**
+   * Removes a color scheme by name.
+   * @param {string} name - Name of the color scheme to remove
+   * @returns {{ [key: string]: ColorMap }} Updated alternate colors object
+   */
   ejectColorScheme(name:string) {
     const currentAlternateColors = this.alternateColorsScheme ?? {}
 
@@ -95,8 +153,15 @@ class ThemeStore {
   }
 }
 
+/**
+ * Global theme store instance.
+ */
 export const themeStore = new ThemeStore()
 
+/**
+ * Computed store that combines theme and color scheme for reactive updates.
+ * @returns {ThemeState} Combined theme state with theme and colorScheme
+ */
 export const themeStoreComputed = computed([
   themeStore.themeStore,
   themeStore.colorSchemeStore,

package/src/{lib → theme}/validateTheme.ts

@@ -1,5 +1,18 @@
 import { Theme } from '../types/theme'
 
+/**
+ * Validates and normalizes a theme object.
+ * Ensures all alternate color schemes include the same keys as `colors`,
+ * and merges `baseColors` into `colors` and `alternateColors`.
+ *
+ * @template T extends Theme
+ * @param {T} theme - The theme to validate.
+ * @throws {Error} If an alternate scheme is missing a required color.
+ * @returns {T & {
+ *   alternateColors: Record<string, Record<string, string>>,
+ *   colors: Record<string, string>
+ * }} The validated theme with merged colors.
+ */
 export function validateTheme<T extends Theme>(theme: T) {
   const baseColors = theme.baseColors
   

package/src/tools/colors.ts

@@ -1,5 +1,9 @@
-import { ColorMap } from '../types'
-
+/**
+ * Converts a hex color to HSL format.
+ * 
+ * @param {string} hex - Hex color string (e.g., '#ff5733')
+ * @returns {object} HSL object with h (0-360), s (0-100), l (0-100)
+ */
 export function hexToHSL(hex: string) {
   const r = parseInt(hex.slice(1, 3), 16) / 255
   const g = parseInt(hex.slice(3, 5), 16) / 255
@@ -26,6 +30,14 @@ export function hexToHSL(hex: string) {
   }
 }
 
+/**
+ * Converts HSL values to hex color format.
+ * 
+ * @param {number} h - Hue (0-360)
+ * @param {number} s - Saturation (0-100)
+ * @param {number} l - Lightness (0-100)
+ * @returns {string} Hex color string
+ */
 export function hslToHex(h: number, s: number, l: number): string {
   s /= 100
   l /= 100
@@ -37,6 +49,12 @@ export function hslToHex(h: number, s: number, l: number): string {
   return `#${[f(0), f(8), f(4)].map(x => x.toString(16).padStart(2, '0')).join('')}`
 }
 
+/**
+ * Converts a hex color to RGB format.
+ * 
+ * @param {string} hex - Hex color string (e.g., '#ff5733')
+ * @returns {object} RGB object with r, g, b values (0-255)
+ */
 export function hexToRGB(hex: string) {
   const r = parseInt(hex.slice(1, 3), 16)
   const g = parseInt(hex.slice(3, 5), 16)
@@ -44,6 +62,14 @@ export function hexToRGB(hex: string) {
   return { r, g, b }
 }
 
+/**
+ * Converts HSL values to RGB format.
+ * 
+ * @param {number} h - Hue (0-360)
+ * @param {number} s - Saturation (0-100)
+ * @param {number} l - Lightness (0-100)
+ * @returns {object} RGB object with r, g, b values (0-255)
+ */
 export function hslToRGB(h: number, s: number, l: number) {
   s /= 100
   l /= 100
@@ -59,47 +85,56 @@ export function hslToRGB(h: number, s: number, l: number) {
   }
 }
 
-const lightnesses = [95, 85, 75, 60, 45, 30, 27, 21, 16, 10]
-
-const defaultLightnessMap = Object.fromEntries(
-  lightnesses.map((l, i) => {
-    const step = ((i + 1) * 100).toString()
-    return [step, l]
-  }),
-)
-
-const alphas = [0.05, 0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.70, 0.80, 0.90]
-
-const defaultAlphasMap = Object.fromEntries(
-  alphas.map((a, i) => {
-    const step = ((i + 1) * 100).toString()
-    return [step, a]
-  }),
-)
-
-export function generateColorScheme(
-  anchorHex: string,
-  prefix = 'primary',
-  lightnesses:typeof defaultLightnessMap = defaultLightnessMap,
-  alphas: typeof defaultAlphasMap = defaultAlphasMap,
-): ColorMap {
-  const { h, s } = hexToHSL(anchorHex)
-  const baseRGB = hexToRGB(anchorHex)
-
-  const scheme: ColorMap = {}
-
-  Object.entries(lightnesses).forEach(([step, lightness]) => {
-    const rgb = hslToRGB(h, s, lightness)
-    scheme[`${prefix}Solid${step}`] = `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 1.00)`
-  })
+/**
+ * Converts RGB values to HSL format.
+ * 
+ * @param {object} rgb - RGB object with r, g, b values (0-255)
+ * @returns {object} HSL object with h (0-360), s (0-100), l (0-100)
+ */
+export function rgbToHSL(rgb: { r: number; g: number; b: number }): { h: number; s: number; l: number } {
+  const r = rgb.r / 255
+  const g = rgb.g / 255
+  const b = rgb.b / 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  let h = 0
+  let s = 0
+  const l = (max + min) / 2
 
-  Object.entries(alphas).forEach(([step, alpha]) => {
-    scheme[`${prefix}Transparent${step}`] = `rgba(${baseRGB.r}, ${baseRGB.g}, ${baseRGB.b}, ${alpha.toFixed(2)})`
-  })
+  if (max !== min) {
+    const d = max - min
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+    
+    switch (max) {
+      case r:
+        h = (g - b) / d + (g < b ? 6 : 0)
+        break
+      case g:
+        h = (b - r) / d + 2
+        break
+      case b:
+        h = (r - g) / d + 4
+        break
+    }
+    
+    h /= 6
+  }
 
-  return scheme
+  return {
+    h: Math.round(h * 360),
+    s: Math.round(s * 100),
+    l: Math.round(l * 100)
+  }
 }
 
+/**
+ * Calculates the relative luminance of an RGB color.
+ * Uses the WCAG formula for accessibility calculations.
+ * 
+ * @param {object} rgb - RGB object with r, g, b values (0-255)
+ * @returns {number} Luminance value (0-1)
+ */
 export function getLuminance({ r, g, b }: { r: number; g: number; b: number }): number {
   const [R, G, B] = [r, g, b].map(c => {
     const channel = c / 255
@@ -111,6 +146,15 @@ export function getLuminance({ r, g, b }: { r: number; g: number; b: number }):
   return 0.2126 * R + 0.7152 * G + 0.0722 * B
 }
 
+/**
+ * Determines the best text color (dark or light) for a given background.
+ * Uses luminance calculation for optimal contrast.
+ * 
+ * @param {string} backgroundHex - Background hex color
+ * @param {string} darkColor - Dark text color option
+ * @param {string} lightColor - Light text color option
+ * @returns {string} Recommended text color
+ */
 export function getTextColor(backgroundHex: string, darkColor = 'black', lightColor = 'white'): string {
   const rgb = hexToRGB(backgroundHex)
   const luminance = getLuminance(rgb)

package/src/tools/deepClone.ts

@@ -0,0 +1,10 @@
+import rfdc from 'rfdc'
+
+/**
+ * Creates a deep clone of any JavaScript object or value.
+ * Uses rfdc (Really Fast Deep Clone) for optimal performance.
+ * 
+ * @param {T} obj - The object or value to clone
+ * @returns {T} A deep copy of the input
+ */
+export const deepClone = rfdc()

package/src/tools/deepmerge.ts

@@ -0,0 +1,10 @@
+/**
+ * Deep merge constructor from Fastify's optimized implementation.
+ * Returns a merge function that recursively merges objects with high performance.
+ * By default, arrays are concatenated and objects are deeply merged.
+ * 
+ * @example
+ * const merger = deepmerge()
+ * const result = merger(target, source)
+ */
+export { default as deepmerge } from '@fastify/deepmerge'

package/src/{lib → tools}/hashKey.ts

@@ -3,6 +3,13 @@ import { sha256 } from 'js-sha256'
 const styleKey = '@styles-version'
 const version = require('../../package.json')?.version
 
+/**
+ * Generates a SHA-256 hash from an array with automatic version injection.
+ * Appends package version to the array for cache invalidation purposes.
+ * 
+ * @param {Array<any>} value - Array to be hashed
+ * @returns {string} SHA-256 hash string
+ */
 export const hashKey = (value: Array<any>): string => {
   value.push({ [styleKey]: version })
 

package/src/tools/index.ts

@@ -1 +1,6 @@
-export * as colorTools from './colors'
+export * as colorTools from './colors'
+export * from './hashKey'
+export * from './minifier'
+export * from './multiplierProperty'
+export * from './deepClone'
+export * from './deepmerge'

package/src/tools/minifier.ts

@@ -0,0 +1,38 @@
+import { compressToBase64, decompressFromBase64 } from 'lz-string'
+
+/**
+ * Compresses any value to a Base64 string using LZ compression.
+ * Returns the original value if falsy.
+ * 
+ * @param {any} value - Value to compress
+ * @returns {string|any} Compressed Base64 string or original falsy value
+ */
+export function compress(value: any): any {
+  if (!value) return value
+  
+  return compressToBase64(JSON.stringify(value))
+}
+
+/**
+ * Decompresses a Base64 string back to its original value.
+ * Returns the original value if falsy.
+ * 
+ * @param {any} value - Compressed Base64 string to decompress
+ * @returns {any} Original decompressed value or original falsy value
+ */
+export function decompress(value: any): any {
+  if (!value) return value
+
+  const decoded = decompressFromBase64(value)
+
+  return JSON.parse(decoded)
+}
+
+/**
+ * Utility object containing compress and decompress functions.
+ * Useful for data compression/decompression operations.
+ */
+export const minifier = {
+  compress,
+  decompress,
+}