@codeleap/styles 6.3.0 → 6.8.0

package/src/lib/tests/createStylesWithContext.spec.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeEach } from 'bun:test'
+import { createStyles, createStylesWithContext, CONTEXT_FACTORY_SYMBOL } from '../createStyles'
+import { themeStore } from '../../theme'
+import { mockTheme, MockedTheme } from '../../tests/theme'
+
+describe('createStylesWithContext (web — isBrowser: true)', () => {
+  let currentTheme: MockedTheme = null as any
+
+  beforeEach(() => {
+    mockTheme({ isBrowser: true })
+    currentTheme = themeStore.theme as unknown as MockedTheme
+  })
+
+  it('exposes the factory function via CONTEXT_FACTORY_SYMBOL', () => {
+    const factory = (theme: any, context: { isActive: boolean }) => ({
+      wrapper: { color: context.isActive ? theme.colors.neutralSo : theme.colors.secondary },
+    })
+
+    const styles = createStylesWithContext(factory as any)
+
+    expect((styles as any)[CONTEXT_FACTORY_SYMBOL]).toBe(factory)
+  })
+
+  it('plain createStyles proxy returns undefined for CONTEXT_FACTORY_SYMBOL', () => {
+    const styles = createStyles((theme: any) => ({
+      wrapper: { color: theme.colors.neutralSo },
+    }))
+
+    expect((styles as any)[CONTEXT_FACTORY_SYMBOL]).toBeUndefined()
+  })
+
+  it('returns expected styles when accessed with default (empty) context', () => {
+    const styles = createStylesWithContext((theme: any, context: { multiplier?: number }) => ({
+      wrapper: { padding: (context.multiplier ?? 1) * 8 },
+    }))
+
+    expect(styles.wrapper).toEqual({ padding: 8 })
+  })
+
+  it('re-evaluates on every property access (proxy behavior)', () => {
+    let callCount = 0
+
+    const styles = createStylesWithContext((theme: any, context: {}) => {
+      callCount++
+      return { wrapper: { color: theme.colors.neutralSo } }
+    })
+
+    callCount = 0
+
+    styles.wrapper
+    styles.wrapper
+    styles.wrapper
+
+    expect(callCount).toBe(3)
+  })
+
+  it('reflects theme changes on subsequent accesses', () => {
+    const styles = createStylesWithContext((theme: any, _context: {}) => ({
+      wrapper: { color: theme.colors.buttonRegularPrimaryBgDefault },
+    }))
+
+    // CSS var reference is static — same regardless of active scheme.
+    // The browser CSS cascade handles the actual color switch.
+    expect(styles.wrapper).toEqual({ color: 'var(--cl-buttonRegularPrimaryBgDefault)' })
+
+    currentTheme.setColorScheme('dark')
+
+    expect(styles.wrapper).toEqual({ color: 'var(--cl-buttonRegularPrimaryBgDefault)' })
+  })
+
+  it('returns undefined for non-existent keys', () => {
+    const styles = createStylesWithContext((_theme: any, _context: {}) => ({
+      wrapper: { color: 'red' },
+    }))
+
+    expect((styles as any).nonExistent).toBeUndefined()
+  })
+})
+
+describe('createStylesWithContext (RN — isBrowser: false)', () => {
+  let currentTheme: MockedTheme = null as any
+
+  beforeEach(() => {
+    mockTheme({ isBrowser: false })
+    currentTheme = themeStore.theme as unknown as MockedTheme
+  })
+
+  it('returns raw RGBA values when isBrowser is false', () => {
+    const styles = createStylesWithContext((_theme: any, _context: {}) => ({
+      wrapper: { color: _theme.colors.neutralSolid500 },
+    }))
+
+    expect(styles.wrapper).toEqual({ color: 'rgba(136, 136, 136, 1.00)' })
+  })
+
+  it('currentSchemeColors reflects active scheme on RN', () => {
+    const styles = createStylesWithContext((_theme: any, _context: {}) => ({
+      wrapper: { color: _theme.currentSchemeColors.buttonRegularPrimaryBgDefault },
+    }))
+
+    expect(styles.wrapper).toEqual({ color: 'rgba(43, 105, 122, 1.00)' })
+
+    currentTheme.setColorScheme('dark')
+
+    const darkValue = currentTheme.currentSchemeColors.buttonRegularPrimaryBgDefault as string
+    expect(styles.wrapper).toEqual({ color: darkValue })
+  })
+})

package/src/tests/theme.ts

@@ -6,7 +6,11 @@ import darkMode from './colors/darkMode'
 import { createTheme } from '../lib'
 import { validateTheme } from '../theme'
 
-export const mockTheme = () => {
+type MockThemeOptions = {
+  isBrowser?: boolean
+}
+
+export const mockTheme = ({ isBrowser = true }: MockThemeOptions = {}) => {
   return createTheme(
     validateTheme({
       baseColors,
@@ -46,7 +50,7 @@ export const mockTheme = () => {
       icons: {},
       presets: {},
       values: {},
-      isBrowser: true,
+      isBrowser,
     }),
     {
       set: (name, colorSchema) => {},

package/src/theme/generateColorScheme.ts

@@ -20,25 +20,28 @@ const defaultAlphasMap = Object.fromEntries(
 )
 
 /**
- * Generates a complete color scheme from an anchor color.
- * Creates solid variants with different lightness and transparent variants.
- * 
- * @param {string} anchorHex - Base hex color for the scheme
- * @param {string} prefix - Prefix for generated color names
- * @param {object} lightnesses - Custom lightness mapping
- * @param {object} alphas - Custom alpha mapping
- * @returns {ColorMap} Complete color scheme object
+ * Derives a 20-token color ramp from a single anchor hex color.
+ *
+ * Produces two groups of tokens:
+ * - **10 solid tokens** (`{prefix}Solid100` … `{prefix}Solid1000`) — vary the lightness
+ *   of the anchor's hue/saturation from ~95 L (lightest) to ~10 L (darkest).
+ * - **10 transparent tokens** (`{prefix}Transparent100` … `{prefix}Transparent1000`) —
+ *   keep the anchor's exact RGB channels but increase alpha from 0.05 to 0.90.
+ *
+ * Default lightness steps: `[95, 85, 75, 60, 45, 30, 27, 21, 16, 10]`.
+ * Default alpha steps: `[0.05, 0.10, …, 0.90]`.
+ * Both can be overridden by passing custom maps (step → value).
  */
 export function generateColorScheme(
   anchorHex: string,
   prefix = 'primary',
   lightnesses:typeof defaultLightnessMap = defaultLightnessMap,
   alphas: typeof defaultAlphasMap = defaultAlphasMap,
-): ColorMap {
+): Record<string, string> {
   const { h, s } = colorTools.hexToHSL(anchorHex)
   const baseRGB = colorTools.hexToRGB(anchorHex)
 
-  const scheme: ColorMap = {}
+  const scheme: Record<string, string> = {}
 
   Object.entries(lightnesses).forEach(([step, lightness]) => {
     const rgb = colorTools.hslToRGB(h, s, lightness)

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

@@ -75,13 +75,13 @@ describe('ThemeStore - Heavy Load Tests', () => {
     })
 
     it('should handle massive color schemes with deep nesting', () => {
-      const colorSchemes = {}
+      const colorSchemes: Record<string, any> = {}
       const schemeCount = 1000
       const colorsPerScheme = 100
 
       // Generate massive color schemes
       for (let scheme = 0; scheme < schemeCount; scheme++) {
-        const colors = {}
+        const colors: Record<string, any> = {}
         for (let color = 0; color < colorsPerScheme; color++) {
           colors[`color_${color}`] = {
             primary: `#${(scheme * color).toString(16).padStart(6, '0')}`,
@@ -135,9 +135,10 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
         // Inject scheme
         const injected = store.injectColorScheme(schemeName, colors)
-        expect(injected[schemeName]).toBeDefined()
-        expect(injected[schemeName].primary).toBe(colors.primary)
-        expect(injected[schemeName].secondary).toBe('#111111') // inherited
+        const scheme = injected[schemeName] as Record<string, string>
+        expect(scheme).toBeDefined()
+        expect(scheme.primary).toBe(colors.primary)
+        expect(scheme.secondary).toBe('#111111') // inherited
 
         // Every 10th operation, eject some schemes
         if (i % 10 === 0 && i > 0) {
@@ -157,10 +158,10 @@ describe('ThemeStore - Heavy Load Tests', () => {
     it('should handle massive variants with complex structures', () => {
       const componentCount = 500
       const variantsPerComponent = 50
-      const variants = {}
+      const variants: Record<string, any> = {}
 
       for (let comp = 0; comp < componentCount; comp++) {
-        const componentVariants = {}
+        const componentVariants: Record<string, any> = {}
         for (let variant = 0; variant < variantsPerComponent; variant++) {
           componentVariants[`variant_${variant}`] = {
             className: `comp-${comp}-var-${variant}`,
@@ -229,7 +230,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
         if (i % 200 === 0) {
           expect(getThemeStore()?.iteration).toBe(i)
           expect(store.colorScheme).toBe(`scheme_${i % 50}`)
-          expect(store.variants[`component_${i}`]).toBeDefined()
+          expect((store.variants as any)[`component_${i}`]).toBeDefined()
         }
       }
 
@@ -246,7 +247,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
   describe('function storage and execution stress tests', () => {
     it('should handle thousands of stored functions with complex computations', () => {
       const functionCount = 5000
-      const theme = {
+      const theme: Record<string, Record<string, any>> = {
         colors: {},
         spacing: {},
         calculators: {},
@@ -259,10 +260,10 @@ describe('ThemeStore - Heavy Load Tests', () => {
       // Store various types of functions
       for (let i = 0; i < functionCount; i++) {
         // Simple calculators
-        theme.calculators[`calc_${i}`] = (value) => value * (i + 1)
+        theme.calculators[`calc_${i}`] = (value: any) => value * (i + 1)
 
         // Complex transformers
-        theme.transformers[`transform_${i}`] = (input) => {
+        theme.transformers[`transform_${i}`] = (input: any) => {
           return {
             scaled: input * Math.pow(2, i % 10),
             offset: input + (i * 3.14159),
@@ -284,7 +285,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
         }
 
         // Validators
-        theme.validators[`validate_${i}`] = (value) => {
+        theme.validators[`validate_${i}`] = (value: any) => {
           return value !== null &&
             value !== undefined &&
             (typeof value === 'number' ? value >= i : value.length >= i % 10)
@@ -347,15 +348,15 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
       // Create deeply nested function chains
       const theme = {
-        fibonacci: {},
-        factorial: {},
-        compose: {},
-        pipeline: {},
+        fibonacci: {} as Record<string, any>,
+        factorial: {} as Record<string, any>,
+        compose: {} as Record<string, any>,
+        pipeline: {} as Record<string, any>,
       }
 
       // Fibonacci functions
       for (let i = 0; i < depth; i++) {
-        theme.fibonacci[`fib_${i}`] = (n) => {
+        theme.fibonacci[`fib_${i}`] = (n: any) => {
           if (n <= 1) return n
           if (i > 0 && theme.fibonacci[`fib_${i - 1}`]) {
             return theme.fibonacci[`fib_${i - 1}`](n - 1) + theme.fibonacci[`fib_${i - 1}`](n - 2)
@@ -366,7 +367,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
       // Factorial chains
       for (let i = 0; i < depth; i++) {
-        theme.factorial[`fact_${i}`] = (n) => {
+        theme.factorial[`fact_${i}`] = (n: any) => {
           if (n <= 1) return 1
           const prevFact = theme.factorial[`fact_${Math.max(0, i - 1)}`]
           return prevFact ? n * prevFact(n - 1) : n
@@ -375,7 +376,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
       // Function composition
       for (let i = 0; i < depth; i++) {
-        theme.compose[`comp_${i}`] = (value) => {
+        theme.compose[`comp_${i}`] = (value: any) => {
           let result = value
           for (let j = 0; j <= i && j < 10; j++) {
             result = Math.sqrt(Math.abs(result * (j + 1)))
@@ -386,13 +387,13 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
       // Pipeline functions
       for (let i = 0; i < depth; i++) {
-        theme.pipeline[`pipe_${i}`] = (input) => {
+        theme.pipeline[`pipe_${i}`] = (input: any) => {
           const steps = [
-            (x) => x * 2,
-            (x) => x + i,
-            (x) => Math.pow(x, 1.5),
-            (x) => x % 1000,
-            (x) => theme.compose[`comp_${Math.min(i, depth - 1)}`]?.(x) || x,
+            (x: any) => x * 2,
+            (x: any) => x + i,
+            (x: any) => Math.pow(x, 1.5),
+            (x: any) => x % 1000,
+            (x: any) => theme.compose[`comp_${Math.min(i, depth - 1)}`]?.(x) || x,
           ]
           return steps.reduce((acc, fn) => fn(acc), input)
         }
@@ -449,7 +450,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
       const factoryCount = 1000
       const generatedPerFactory = 10
 
-      const theme = {
+      const theme: Record<string, Record<string, any>> = {
         factories: {},
         generated: {},
         dynamicComputed: {},
@@ -459,17 +460,17 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
       // Create function factories
       for (let i = 0; i < factoryCount; i++) {
-        theme.factories[`factory_${i}`] = (config) => {
+        theme.factories[`factory_${i}`] = (config: any) => {
           return {
-            calculator: (value) => value * (config.multiplier || 1) + (config.offset || 0),
-            validator: (value) => value >= (config.min || 0) && value <= (config.max || 1000),
-            transformer: (value) => ({
+            calculator: (value: any) => value * (config.multiplier || 1) + (config.offset || 0),
+            validator: (value: any) => value >= (config.min || 0) && value <= (config.max || 1000),
+            transformer: (value: any) => ({
               original: value,
               scaled: value * (config.scale || 1),
               formatted: `${config.prefix || ''}${value}${config.suffix || ''}`,
               computed: Math.pow(value, config.power || 1),
             }),
-            composer: (...fns) => (value) => fns.reduce((acc, fn) => fn(acc), value),
+            composer: (...fns: any[]) => (value: any) => fns.reduce((acc, fn) => fn(acc), value),
           }
         }
 
@@ -490,7 +491,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
           theme.generated[`gen_${i}_${j}`] = generatedFunctions
 
           // Create dynamic computed values
-          theme.dynamicComputed[`comp_${i}_${j}`] = (input) => {
+          theme.dynamicComputed[`comp_${i}_${j}`] = (input: any) => {
             const calc = generatedFunctions.calculator(input)
             const valid = generatedFunctions.validator(calc)
             const transform = generatedFunctions.transformer(calc)
@@ -543,8 +544,8 @@ describe('ThemeStore - Heavy Load Tests', () => {
               const generated = getThemeStore()?.generated[`gen_${i}_${j}`]
               if (generated?.composer) {
                 const composed = generated.composer(
-                  (x) => x * 2,
-                  (x) => x + 10,
+                  (x: any) => x * 2,
+                  (x: any) => x + 10,
                   generated.calculator,
                 )(testValue)
                 if (typeof composed === 'number') executionCount++
@@ -577,7 +578,7 @@ describe('ThemeStore - Heavy Load Tests', () => {
 
       for (let set = 0; set < hugeSets; set++) {
         // Create massive theme
-        const hugeTheme = {
+        const hugeTheme: Record<string, Record<string, any>> = {
           colors: {},
           spacing: {},
           typography: {},
@@ -597,9 +598,9 @@ describe('ThemeStore - Heavy Load Tests', () => {
         store.setTheme(hugeTheme)
 
         // Create massive color schemes
-        const hugeColorSchemes = {}
+        const hugeColorSchemes: Record<string, any> = {}
         for (let i = 0; i < itemsPerSet; i++) {
-          const scheme = {}
+          const scheme: Record<string, any> = {}
           for (let j = 0; j < 50; j++) {
             scheme[`color_${j}`] = `#${(i * j).toString(16).padStart(6, '0')}`
           }

package/src/theme/themeStore.ts

@@ -5,7 +5,7 @@ import { map, computed, atom } from 'nanostores'
  * Theme state interface containing theme and color scheme information.
  */
 export type ThemeState = {
-  theme: AppTheme<Theme> | null
+  theme: ITheme | null
   colorScheme: string | null
 }
 
@@ -18,9 +18,9 @@ export class ThemeStore {
 
   public readonly colorSchemeStore = atom<string | null>(null)
 
-  public readonly themeStore = map<ITheme | null>(null)
-
-  public readonly variantsStore = map<IAppVariants>({})
+  public readonly themeStore = atom<ITheme | null>(null)
+  
+  public readonly variantsStore = map<IAppVariants>({} as IAppVariants)
 
   /**
    * Gets the current theme.
@@ -35,7 +35,8 @@ export class ThemeStore {
    * @returns {AppTheme<Theme>} Current theme cast to AppTheme type
    */
   get themeTyped() {
-    return this.themeStore.get() as unknown as AppTheme<Theme>
+    const theme = this.themeStore.get()
+    return theme ? theme as unknown as AppTheme<Theme> : null
   }
 
   /**
@@ -159,8 +160,10 @@ export class ThemeStore {
 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
+ * Derived nanostores `computed` that combines `themeStore` and `colorSchemeStore`
+ * into a single `ThemeState` atom. Components subscribe to this via `useTheme`
+ * so they re-render only when either the theme object or the active color scheme
+ * changes — not on every `ThemeStore` method call.
  */
 export const themeStoreComputed = computed([
   themeStore.themeStore,

package/src/theme/validateTheme.ts

@@ -22,7 +22,7 @@ export function validateTheme<T extends Theme>(theme: T) {
 
   const requiredColors = Object.keys(colors)
 
-  const mergedAlternateColors = {}
+  const mergedAlternateColors: Record<string, any> = {}
   
   if (alternateColors) {
     for (const [colorSchemeName, colorSchemeColors] of Object.entries(alternateColors)) {

package/src/tools/colors.ts

@@ -1,8 +1,7 @@
 /**
- * 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)
+ * Expects a 7-character hex string (`#rrggbb`). Shorter forms (3-char, no hash) are
+ * not handled and will produce NaN channels. Returns h in [0, 360], s and l in [0, 100],
+ * all rounded to integers via `Math.round`.
  */
 export function hexToHSL(hex: string) {
   const r = parseInt(hex.slice(1, 3), 16) / 255
@@ -31,12 +30,10 @@ 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
+ * Uses the HSL-to-RGB CSS Color 4 formula (single-pass, no separate hue helper).
+ * Inputs h in [0, 360], s and l in [0, 100]; channels are clamped implicitly by
+ * `Math.min`/`Math.max`. Each channel is individually rounded before hex encoding,
+ * so the round-trip `hexToHSL → hslToHex` may differ by ±1 in the last hex digit.
  */
 export function hslToHex(h: number, s: number, l: number): string {
   s /= 100
@@ -50,10 +47,8 @@ export function hslToHex(h: number, s: number, l: number): string {
 }
 
 /**
- * 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)
+ * Parses only the 6-digit `#rrggbb` form via `parseInt(..., 16)`.
+ * No alpha channel is extracted. Channels are returned as integers in [0, 255].
  */
 export function hexToRGB(hex: string) {
   const r = parseInt(hex.slice(1, 3), 16)
@@ -63,12 +58,9 @@ export function hexToRGB(hex: string) {
 }
 
 /**
- * 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)
+ * Shares the same formula as `hslToHex` but returns separate integer r/g/b channels
+ * instead of a hex string. Useful when you need numeric channels for `rgba(...)` output.
+ * Input ranges: h [0, 360], s [0, 100], l [0, 100].
  */
 export function hslToRGB(h: number, s: number, l: number) {
   s /= 100
@@ -86,10 +78,9 @@ export function hslToRGB(h: number, s: number, l: number) {
 }
 
 /**
- * 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)
+ * Inverse of `hslToRGB`. Normalises each channel from [0, 255] to [0, 1] before
+ * computing. When max === min (achromatic), hue is fixed at 0. All output values are
+ * rounded, so the round-trip `hslToRGB → rgbToHSL` is not guaranteed to be lossless.
  */
 export function rgbToHSL(rgb: { r: number; g: number; b: number }): { h: number; s: number; l: number } {
   const r = rgb.r / 255
@@ -129,11 +120,11 @@ export function rgbToHSL(rgb: { r: number; g: number; b: number }): { h: number;
 }
 
 /**
- * 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)
+ * Implements WCAG 2.x relative luminance (https://www.w3.org/TR/WCAG20/#relativeluminancedef).
+ * Channels are linearised with the sRGB transfer function: values ≤ 0.03928 use
+ * the linear segment (C / 12.92); values above use the gamma curve ((C + 0.055) / 1.055)^2.4.
+ * The luminance coefficients are 0.2126 R + 0.7152 G + 0.0722 B, reflecting the
+ * eye's greater sensitivity to green. Returns a value in [0, 1].
  */
 export function getLuminance({ r, g, b }: { r: number; g: number; b: number }): number {
   const [R, G, B] = [r, g, b].map(c => {
@@ -147,13 +138,10 @@ export function getLuminance({ r, g, b }: { r: number; g: number; b: number }):
 }
 
 /**
- * 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
+ * Uses a luminance threshold of **0.5** (not the WCAG 4.5:1 contrast ratio) to pick
+ * between two text colours. Backgrounds with luminance > 0.5 are treated as light and
+ * receive `darkColor`; all others receive `lightColor`. This is a perceptual shortcut —
+ * use explicit contrast-ratio checks for accessibility-critical situations.
  */
 export function getTextColor(backgroundHex: string, darkColor = 'black', lightColor = 'white'): string {
   const rgb = hexToRGB(backgroundHex)

package/src/tools/deepClone.ts

@@ -1,10 +1,8 @@
 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
+ * rfdc clone function configured with default options (no circular-reference support,
+ * proto: false). Does not handle `Date`, `RegExp`, or `Buffer` fields — they are copied
+ * by reference. Use only on plain style/theme objects.
  */
 export const deepClone = rfdc()

package/src/tools/deepmerge.ts

@@ -1,10 +1,12 @@
 /**
- * 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.
- * 
+ * Re-exports `@fastify/deepmerge`'s factory function. Call it once with options
+ * (e.g., `deepmerge({ all: true })`) to obtain a variadic merge function.
+ * Passing `{ all: true }` merges arrays by index rather than concatenating them —
+ * this is the mode used throughout the style registry for variant merging.
+ * The returned merger is not idempotent: source properties always overwrite target.
+ *
  * @example
- * const merger = deepmerge()
- * const result = merger(target, source)
+ * const merge = deepmerge({ all: true })
+ * const result = merge(base, override1, override2)
  */
 export { default as deepmerge } from '@fastify/deepmerge'

package/src/tools/hashKey.ts

@@ -4,11 +4,10 @@ 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
+ * Mutates the input array by appending `{ '@styles-version': <pkg.version> }` before
+ * hashing — meaning callers must not rely on the array being unchanged after the call.
+ * The version injection ensures any cache key computed against an older package version
+ * is automatically invalid after a library upgrade.
  */
 export const hashKey = (value: Array<any>): string => {
   value.push({ [styleKey]: version })

package/src/tools/minifier.ts

@@ -1,11 +1,11 @@
 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
+ * Serialises `value` with `JSON.stringify` then LZ-compresses to a Base64 string.
+ * Returns the value unchanged (without throwing) when it is falsy, so callers
+ * do not need to guard against `null`/`undefined`/`''` inputs.
+ * Non-serialisable values (functions, `undefined` inside objects, circular refs)
+ * will be silently dropped by `JSON.stringify`.
  */
 export function compress(value: any): any {
   if (!value) return value
@@ -14,11 +14,10 @@ export function compress(value: any): any {
 }
 
 /**
- * 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
+ * Reverses `compress`: LZ-decompresses the Base64 string then parses the JSON.
+ * Returns the value unchanged when falsy. Will throw if `value` is a non-empty
+ * string that is not valid LZ-Base64, or if the decompressed payload is not
+ * valid JSON — callers should guard accordingly.
  */
 export function decompress(value: any): any {
   if (!value) return value
@@ -29,8 +28,8 @@ export function decompress(value: any): any {
 }
 
 /**
- * Utility object containing compress and decompress functions.
- * Useful for data compression/decompression operations.
+ * Convenience namespace so callsites can import a single symbol and call
+ * `minifier.compress` / `minifier.decompress` without named imports.
  */
 export const minifier = {
   compress,

package/src/tools/tests/deepClone.spec.ts

@@ -44,8 +44,8 @@ describe('deepClone', () => {
     expect(cloned).not.toBe(original)
     expect(cloned[2]).not.toBe(original[2])
     
-    cloned[2][0] = 5
-    expect(original[2][0]).toBe(3)
+    ;(cloned[2] as any)[0] = 5
+    expect((original[2] as any)[0]).toBe(3)
   })
 
   test('should handle complex nested structures', () => {