@selvajs/ui 6.0.0-beta.8 → 6.0.0

package/src/lib/utils/color.ts

@@ -1,32 +1,30 @@
-// Helper to convert hex to OKLCH
+// Hex → OKLCH. A non-null input that isn't a 6-digit hex comes back unchanged, so
+// callers can pass through CSS colors this function doesn't understand; null gives ''.
 export const hexToOklch = (hex: string | null): string => {
 	if (!hex) return '';
 
-	// Normalize hex (remove # if present)
 	const normalized = hex.replace(/^#/, '');
 
-	// If it's not a valid hex color, return as-is
 	if (!/^[0-9A-Fa-f]{6}$/.test(normalized)) {
 		return hex;
 	}
 
-	// Parse hex to RGB
 	const r = parseInt(normalized.slice(0, 2), 16) / 255;
 	const g = parseInt(normalized.slice(2, 4), 16) / 255;
 	const b = parseInt(normalized.slice(4, 6), 16) / 255;
 
-	// Convert RGB to linear RGB
+	// sRGB transfer function, inverted: gamma-encoded channel → linear light.
 	const toLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
 	const lr = toLinear(r);
 	const lg = toLinear(g);
 	const lb = toLinear(b);
 
-	// Convert linear RGB to XYZ
+	// Linear sRGB → CIE XYZ (D65 white point).
 	const x = lr * 0.4124564 + lg * 0.3575761 + lb * 0.1804375;
 	const y = lr * 0.2126729 + lg * 0.7151522 + lb * 0.072175;
 	const z = lr * 0.0193339 + lg * 0.119192 + lb * 0.9503041;
 
-	// Convert XYZ to OKLab
+	// XYZ → OKLab: the M1 cone-response matrix, cube root, then the M2 matrix.
 	const l_ = Math.cbrt(0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z);
 	const m_ = Math.cbrt(0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z);
 	const s_ = Math.cbrt(0.0482003018 * x + 0.2643662691 * y + 0.633851707 * z);
@@ -35,11 +33,10 @@ export const hexToOklch = (hex: string | null): string => {
 	const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
 	const b_lab = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
 
-	// Convert to LCH
+	// OKLab → OKLCH: chroma and hue as polar coordinates of (a, b).
 	const C = Math.sqrt(a * a + b_lab * b_lab);
 	let H = (Math.atan2(b_lab, a) * 180) / Math.PI;
 	if (H < 0) H += 360;
 
-	// Format as OKLCH (round to reasonable precision)
 	return `oklch(${L.toFixed(3)} ${C.toFixed(3)} ${H.toFixed(1)})`;
 };

package/src/lib/utils/debounce.ts

@@ -1,14 +1,4 @@
-/**
- * Debounce utility - delays function execution until after a specified wait time
- * has elapsed since the last time it was invoked.
- *
- * Use for text inputs, search boxes, etc. where you want to wait for the user
- * to finish typing before executing.
- *
- * @param func The function to debounce
- * @param wait The delay in milliseconds
- * @returns A debounced version of the function with a cancel method
- */
+/** Runs `func` once `wait` ms have passed with no further calls. `cancel()` drops a pending call. */
 export function debounce<T extends (...args: any[]) => any>(
 	func: T,
 	wait: number

package/src/lib/utils/loadScript.ts

@@ -1,13 +1,8 @@
 const scriptLoaders = new Map<string, Promise<void>>();
 
 /**
- * Load an external script from a CDN with automatic deduplication.
- * All calls to load the same script will share a single promise,
- * preventing duplicate script tags and race conditions.
- *
- * @param src The script URL
- * @param options Script attributes (crossOrigin, async, etc.)
- * @returns Promise that resolves when script is loaded
+ * Appends a `<script>` for `src` and resolves on load. Concurrent calls for the same URL share
+ * one promise, so a script never gets a second tag. A failed load is evicted so a retry can run.
  */
 export function loadScript(
 	src: string,