@codeleap/styles 6.2.3 → 6.8.0

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', () => {

package/src/types/cache.ts

@@ -1,2 +1,12 @@
 
+/**
+ * Discriminant union identifying the six cache buckets managed by `StyleCache`.
+ * Each bucket stores a different stage of the style-resolution pipeline:
+ * - `variants` — per-component variant merge results (persisted)
+ * - `common` — shared/common variant lookups (persisted)
+ * - `components` — final merged component output (persisted)
+ * - `styles` — `createStyles` call results (in-memory)
+ * - `compositions` — composition style resolution (in-memory)
+ * - `responsive` — responsive breakpoint style resolution (in-memory)
+ */
 export type CacheType = 'variants' | 'common' | 'styles' | 'compositions' | 'responsive' | 'components'

package/src/types/component.ts

@@ -1,7 +1,24 @@
-import { AnyRecord, IJSX } from './core'
+import { AnyRecord, ICSS, IJSX } from './core'
 import { StyleProp, VariantStyleSheet } from './style'
 import React, { JSX } from 'react'
 
+/**
+ * Injects a typed `style` prop onto a component based on the composition keys
+ * inferred from the variant stylesheet. Primarily used when a component's style
+ * prop shape must mirror its variant composition keys exactly.
+ */
+export type StyledProps<VariantStyles extends AnyRecord> = {
+  style?: StyleProp<
+   VariantStyles[keyof VariantStyles] extends Partial<Record<infer K, any>> ? K extends string ? K : never : never,
+    keyof VariantStyles
+  >
+}
+
+/**
+ * Merges external `Props` with variant-aware `style`. If `Props` already declares a
+ * `style` prop whose inner composition type can be inferred, that composition is
+ * preserved; otherwise the composition is derived from `VariantStyles`.
+ */
 export type PropsWithVariants<Props extends AnyRecord, VariantStyles extends AnyRecord> = Omit<Props, 'style'> & {
   style?: StyleProp<
     Extract<keyof Props, 'style'> extends never ? VariantStyles[keyof VariantStyles] : (
@@ -11,11 +28,18 @@ export type PropsWithVariants<Props extends AnyRecord, VariantStyles extends Any
   >
 }
 
+/** Unconstrained function type used for variant callbacks and other callbacks. */
 export type AnyFunction = (...args: any[]) => any
 
-export type StyledComponentProps<Props extends AnyRecord, VariantStyles> = PropsWithVariants<Props, VariantStyles>
+/** Resolved props type for a component that has been bound to a variant stylesheet. */
+export type StyledComponentProps<Props extends AnyRecord, VariantStyles extends AnyRecord> = PropsWithVariants<Props, VariantStyles>
 
-export type StyledComponent<VariantStyles, Props extends AnyRecord = AnyRecord> = (
+/**
+ * A component function that accepts variant-aware style props, plus the registry
+ * metadata fields (`styleRegistryName`, `elements`, `rootElement`) used by the
+ * `CodeleapStyleRegistry` to resolve composition and responsive styles.
+ */
+export type StyledComponent<VariantStyles extends AnyRecord, Props extends AnyRecord = AnyRecord> = (
   (props: StyledComponentProps<Props, VariantStyles>) => IJSX
 ) & {
   styleRegistryName?: string
@@ -23,19 +47,31 @@ export type StyledComponent<VariantStyles, Props extends AnyRecord = AnyRecord>
   rootElement?: string
 }
 
-export type GenericStyledComponentAttributes<Props> = {
+/**
+ * Static attributes attached to every component created by the style system.
+ * `withVariantTypes` narrows the component's style prop to a specific variant stylesheet
+ * without changing the runtime behaviour — it is a TypeScript-only helper.
+ */
+export type GenericStyledComponentAttributes<Props extends AnyRecord> = {
   styleRegistryName?: string
   withVariantTypes?: <VariantStyles extends VariantStyleSheet>(variants: VariantStyles) => StyledComponent<VariantStyles, Props>
   elements?: string[]
   rootElement?: string
 }
 
+/**
+ * A component that hasn't been bound to a specific variant stylesheet yet but carries
+ * the registry metadata needed for the style system to work at runtime.
+ */
 export type GenericStyledComponent<
   Props extends AnyRecord
 > = ((props: Props) => IJSX) & GenericStyledComponentAttributes<Props>
 
+/** Escape-hatch alias for `GenericStyledComponent<any>` used in registry maps. */
 export type AnyStyledComponent = GenericStyledComponent<any>
 
+/** Component function type that optionally accepts `defaultProps` — mirrors React's pattern. */
 export type ComponentWithDefaultProps<P> = ((props: P) => JSX.Element) & { defaultProps?: Partial<P> }
 
-export type StyledComponentWithProps<Props> = ComponentWithDefaultProps<Props> & GenericStyledComponentAttributes<Props>
+/** Combines `ComponentWithDefaultProps` with the style-registry metadata attributes. */
+export type StyledComponentWithProps<Props extends AnyRecord> = ComponentWithDefaultProps<Props> & GenericStyledComponentAttributes<Props>

package/src/types/core.ts

@@ -1,40 +1,100 @@
-
 /* eslint-disable @typescript-eslint/no-empty-interface */
+
+/**
+ * Declaration-merging target for the app's CSS/style property bag.
+ * Platform packages (`@codeleap/web`, `@codeleap/mobile`) augment this interface
+ * with the actual CSS or React Native style properties they support.
+ */
 export interface ICSS {
 
 }
 
+/**
+ * Declaration-merging target for the resolved `AppTheme` object available at runtime.
+ * Consumer apps augment this so that `useTheme()` returns a fully typed theme without
+ * explicit generics at every callsite.
+ */
 export interface ITheme {
 
 }
 
+/**
+ * Declaration-merging target for the JSX element type used by the platform.
+ * Web augments this with `React.ReactElement`; mobile augments with React Native's
+ * equivalent. Allows cross-platform component return types to be typed correctly.
+ */
 export interface IJSX {
 
 }
+
+/**
+ * Declaration-merging target for the app's named breakpoint map.
+ * Augment with `{ sm: unknown; md: unknown; lg: unknown }` (or your own breakpoints)
+ * so that `Breakpoint` and the responsive style API become fully typed.
+ */
 export interface IBreakpoints {
 
 }
 
+/**
+ * Declaration-merging target for the app's color token map.
+ * Augment with the flattened color keys from your theme (e.g., `{ primary: string }`)
+ * so that `color:`, `bg:`, and `borderColor:` variants are narrowed to valid tokens.
+ */
 export interface IColors {
-  
+
 }
 
+/**
+ * Declaration-merging target for the app's border-radius token map.
+ * Augment with keys from `theme.radius` so that `borderRadius:` and `br:` variants
+ * accept only the defined radius tokens.
+ */
 export interface IBorderRadius {
-  
+
 }
 
+/**
+ * Declaration-merging target for app-defined style variants registered via
+ * `createAppVariants`. Augment so that custom variant names are accepted by `StyleProp`.
+ */
 export interface IAppVariants {
-  
+
 }
 
+/**
+ * Declaration-merging target for the app's named size tokens (from `theme.size`).
+ * Augment so that the `size:` dynamic variant is narrowed to valid size keys.
+ */
+export interface ISizes {
+
+}
+
+/**
+ * Declaration-merging target for a single effect object (e.g., a shadow or filter
+ * definition). Shape is platform-specific; augmented by platform packages.
+ */
 export interface IEffect {
-  
+
 }
 
+/**
+ * Declaration-merging target for the named effects map (`theme.effects`).
+ * Augment with `{ shadow: IEffect; ... }` so that `effect:` variants are narrowed.
+ */
 export interface IEffects {
-  
+
 }
 
+/** Convenience alias for an unconstrained key-value record. */
 export type AnyRecord = Record<string, any>
 
+/** Union of all breakpoint names defined via `IBreakpoints` augmentation. */
 export type Breakpoint = keyof IBreakpoints
+
+/**
+ * Runtime context passed to context-aware style factories created with
+ * `createStylesWithContext`. Keys are feature flags or numeric state values
+ * (e.g., `{ isDisabled: true, tabIndex: 2 }`).
+ */
+export type ComponentContext = Record<string, boolean|number>

package/src/types/icon.ts

@@ -1,8 +1,19 @@
 /* eslint-disable @typescript-eslint/no-empty-interface */
 
+/**
+ * Declaration-merging target for the app's named icon set.
+ * Augment with `{ arrowLeft: unknown; close: unknown; ... }` to produce a typed
+ * `AppIcon` union. Shapes are platform-defined; only the keys matter for typing.
+ */
 export interface AppIcons {
 
 }
+
+/** Union of all named icon keys declared in `AppIcons`. Resolves to `never` if not augmented. */
 export type AppIcon = keyof AppIcons
 
+/**
+ * Accepted value for any `icon` prop: either a named `AppIcon` key or an inline
+ * URL in the form `url:<href>` (e.g., `"url:https://example.com/icon.svg"`).
+ */
 export type IconProp = AppIcon | `url:${string}`

package/src/types/spacing.ts

@@ -1,3 +1,7 @@
+/**
+ * Long-form spacing direction suffixes used with `margin` and `padding`.
+ * The empty string `''` represents the un-suffixed property (e.g., `padding`).
+ */
 export const spacingVariants = [
   'Vertical',
   'Horizontal',
@@ -8,6 +12,11 @@ export const spacingVariants = [
   '',
 ] as const
 
+/**
+ * Short-form spacing direction suffixes used with `m` and `p`.
+ * Maps to the long-form via `shortPositionMap` inside `spacingFactory`.
+ * The empty string `''` represents the un-suffixed property (e.g., `p`).
+ */
 export const spacingShortVariants = [
   'y',
   'x',
@@ -18,15 +27,27 @@ export const spacingShortVariants = [
   '',
 ] as const
 
+/** Union of all long-form direction suffixes (e.g., `'Vertical'`, `''`). */
 export type SpacingVariants = typeof spacingVariants[number]
 
+/** Union of all short-form direction suffixes (e.g., `'x'`, `''`). */
 export type SpacingShortVariants = typeof spacingShortVariants[number]
 
+/**
+ * Valid multiplier values for spacing and inset variant strings.
+ * `'auto'` maps to the CSS `auto` keyword; a number is scaled by `baseSpacing`;
+ * `''` is the empty-string terminator used in template literal unions.
+ */
 export type Multiplier =
   | 'auto'
   | number
   | ''
 
+/**
+ * All valid spacing variant strings accepted by `StyleProp`.
+ * Examples: `"paddingVertical:2"`, `"mt:1"`, `"gap:auto"`.
+ * The numeric part is multiplied by `baseSpacing` at resolution time.
+ */
 export type Spacing =
   | `padding${SpacingVariants}:${Multiplier}`
   | `margin${SpacingVariants}:${Multiplier}`

package/src/types/store.ts

@@ -1,3 +1,9 @@
+/**
+ * Minimal key-value storage contract used by `StylePersistor` and `Cache`.
+ * Designed to be implemented by any synchronous store (e.g., MMKV, AsyncStorage
+ * adapters, or `localStorage` wrappers). `getItem` must return `null` (not `undefined`)
+ * when the key is absent — callers use `?? null` guards based on that assumption.
+ */
 export interface StateStorage {
   getItem: (name: string) => any | null
   setItem: (name: string, value: any) => void

package/src/types/style.ts

@@ -10,6 +10,12 @@ type Inset =
   | `left:${Multiplier}`
   | `right:${Multiplier}`
 
+/**
+ * Union of all built-in variant string literals accepted anywhere a style variant
+ * name is valid: spacing shorthands, inset offsets, dynamic token variants (color,
+ * border, cursor, etc.), the static `defaultVariants` keys, app-defined variants,
+ * and named effect tokens.
+ */
 export type CommonVariants =
   Spacing |
   Inset |
@@ -18,12 +24,13 @@ export type CommonVariants =
   keyof IAppVariants |
   `effect:${keyof IEffects}`
 
-type StyleAtom<Composition = AnyRecord, Variants = string, HasBreakpoints = string, HasComposition = string> =
+type StyleAtom<Composition extends string = string, Variants = string, HasBreakpoints = string, HasComposition = string> =
   ICSS |
   Variants |
   CommonVariants |
   boolean |
   null |
+  undefined |
   '' |
 
   (HasBreakpoints extends string ? {
@@ -35,29 +42,49 @@ type StyleAtom<Composition = AnyRecord, Variants = string, HasBreakpoints = stri
   } : null) |
   (HasComposition extends string ?
       Partial<Record<
-        keyof Composition,
-        StyleAtom<AnyRecord, Variants, boolean, boolean> |
-        StyleAtom<AnyRecord, Variants, boolean, boolean>[]
+        Composition,
+        StyleAtom<Composition, Variants, boolean, boolean> |
+        StyleAtom<Composition, Variants, boolean, boolean>[]
       >>
       : null
   )
   | Array<Variants | ICSS | Partial<
     Record<
-      keyof Composition,
-      StyleAtom<AnyRecord, Variants, boolean, boolean> |
-      StyleAtom<AnyRecord, Variants, boolean, boolean>[]
+      Composition,
+      StyleAtom<Composition, Variants, boolean, boolean> |
+      StyleAtom<Composition, Variants, boolean, boolean>[]
     >
   >>
 
+/**
+ * The value accepted by any component's `style` prop. Supports:
+ * - A raw `ICSS` object applied to the root element.
+ * - A variant string (or array of strings) resolved through the registry.
+ * - A composition object mapping sub-element names to their own `StyleAtom`.
+ * - A `{ breakpoints: { [key]: StyleAtom } }` object for responsive overrides.
+ * - An array mixing any of the above — processed left-to-right, last write wins.
+ */
 export type StyleProp<
-  Composition = AnyRecord,
+  Composition extends string = string,
   Variants = string
 > = StyleAtom<Composition, Variants> | StyleAtom<Composition, Variants>[]
 
+/**
+ * Loosely typed variant stylesheet — a record mapping variant names to their style
+ * definitions. Used as the input to `createStyles` and `registerVariants`.
+ */
 export type VariantStyleSheet = Record<string, any>
 
-export type StyledProp<T extends string> = StyleProp<Record<T, ICSS>>
+/** Alias for `StyleProp<T>` scoped to a specific set of composition keys. */
+export type StyledProp<T extends string> = StyleProp<T>
 
+/**
+ * Post-processing function that receives the merged theme and fully resolved variant
+ * styles and returns a (potentially transformed) style record. Useful for injecting
+ * cross-variant logic such as conditional overrides that depend on multiple variant
+ * states simultaneously.
+ */
 export type StyleAggregator<T extends string = any> = (theme: ITheme, style: Record< T, ICSS>) => Record< T, ICSS>
 
-export type StyleRecord<K extends string> = Record<K, ICSS>
+/** Typed record mapping composition/element keys to their resolved `ICSS` values. */
+export type StyleRecord<K extends string> = Record<K, ICSS>