@arolariu/components 0.4.1 → 0.5.0

package/src/lib/color-conversion-utilities.test.ts

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview Tests for color conversion utilities.
+ * @module lib/color-conversion-utilities.test
+ */
+
+import {describe, expect, it} from "vitest";
+import {
+  adjustHexColorLightness,
+  calculateComplementaryHexColor,
+  convertHexToHslString,
+  convertHslToHexString,
+  parseHslStringToComponents,
+  validateHexColorFormat,
+} from "./color-conversion-utilities";
+
+describe("color-conversion-utilities", () => {
+  describe("convertHexToHslString", () => {
+    it("should convert cyan-500 (#06b6d4) to HSL", () => {
+      const result = convertHexToHslString("#06b6d4");
+      // Note: Actual computed value due to floating point math
+      expect(result).toBe("189 94% 43%");
+    });
+
+    it("should convert pink-500 (#ec4899) to HSL", () => {
+      const result = convertHexToHslString("#ec4899");
+      expect(result).toBe("330 81% 60%");
+    });
+
+    it("should handle hex without # prefix", () => {
+      const result = convertHexToHslString("06b6d4");
+      // Note: Same color as with # prefix, same computed HSL
+      expect(result).toBe("189 94% 43%");
+    });
+
+    it("should convert black (#000000) to HSL", () => {
+      const result = convertHexToHslString("#000000");
+      expect(result).toBe("0 0% 0%");
+    });
+
+    it("should convert white (#ffffff) to HSL", () => {
+      const result = convertHexToHslString("#ffffff");
+      expect(result).toBe("0 0% 100%");
+    });
+
+    it("should convert pure red (#ff0000) to HSL", () => {
+      const result = convertHexToHslString("#ff0000");
+      expect(result).toBe("0 100% 50%");
+    });
+
+    it("should convert pure green (#00ff00) to HSL", () => {
+      const result = convertHexToHslString("#00ff00");
+      expect(result).toBe("120 100% 50%");
+    });
+
+    it("should convert pure blue (#0000ff) to HSL", () => {
+      const result = convertHexToHslString("#0000ff");
+      expect(result).toBe("240 100% 50%");
+    });
+
+    it("should handle high lightness colors (l > 0.5)", () => {
+      // Light pink has l > 0.5, which triggers the other saturation calculation branch
+      const result = convertHexToHslString("#ffb6c1");
+      expect(result).toBe("351 100% 86%");
+    });
+
+    it("should handle colors where max is green", () => {
+      // Green dominant color
+      const result = convertHexToHslString("#90ee90");
+      expect(result).toBe("120 73% 75%");
+    });
+
+    it("should handle colors where g < b in red-dominant colors", () => {
+      // Red with more blue than green (magenta-ish)
+      const result = convertHexToHslString("#ff00aa");
+      expect(result).toBe("320 100% 50%");
+    });
+  });
+
+  describe("convertHslToHexString", () => {
+    it("should convert HSL to cyan-500", () => {
+      // Note: HSL to hex conversion may not perfectly round-trip due to rounding
+      const result = convertHslToHexString(189, 94, 43);
+      expect(result.toLowerCase()).toBe("#07b6d5");
+    });
+
+    it("should convert black HSL to hex", () => {
+      const result = convertHslToHexString(0, 0, 0);
+      expect(result.toLowerCase()).toBe("#000000");
+    });
+
+    it("should convert white HSL to hex", () => {
+      const result = convertHslToHexString(0, 0, 100);
+      expect(result.toLowerCase()).toBe("#ffffff");
+    });
+
+    it("should convert pure red HSL to hex", () => {
+      const result = convertHslToHexString(0, 100, 50);
+      expect(result.toLowerCase()).toBe("#ff0000");
+    });
+
+    it("should handle all hue ranges", () => {
+      // Yellow range (60)
+      expect(convertHslToHexString(60, 100, 50).toLowerCase()).toBe("#ffff00");
+      // Cyan range (180)
+      expect(convertHslToHexString(180, 100, 50).toLowerCase()).toBe("#00ffff");
+      // Magenta range (300)
+      expect(convertHslToHexString(300, 100, 50).toLowerCase()).toBe("#ff00ff");
+    });
+
+    it("should handle all hue sectors correctly", () => {
+      // Sector 0-60: red range
+      expect(convertHslToHexString(30, 100, 50).toLowerCase()).toBe("#ff8000");
+      // Sector 60-120: yellow-green range
+      expect(convertHslToHexString(90, 100, 50).toLowerCase()).toBe("#80ff00");
+      // Sector 120-180: green-cyan range
+      expect(convertHslToHexString(150, 100, 50).toLowerCase()).toBe("#00ff80");
+      // Sector 180-240: cyan-blue range
+      expect(convertHslToHexString(210, 100, 50).toLowerCase()).toBe("#0080ff");
+      // Sector 240-300: blue-magenta range
+      expect(convertHslToHexString(270, 100, 50).toLowerCase()).toBe("#8000ff");
+      // Sector 300-360: magenta-red range
+      expect(convertHslToHexString(330, 100, 50).toLowerCase()).toBe("#ff0080");
+    });
+  });
+
+  describe("validateHexColorFormat", () => {
+    it("should return true for valid hex with #", () => {
+      expect(validateHexColorFormat("#06b6d4")).toBe(true);
+    });
+
+    it("should return true for valid hex without #", () => {
+      expect(validateHexColorFormat("06b6d4")).toBe(true);
+    });
+
+    it("should return true for uppercase hex", () => {
+      expect(validateHexColorFormat("#FFFFFF")).toBe(true);
+    });
+
+    it("should return false for 3-digit hex", () => {
+      expect(validateHexColorFormat("#FFF")).toBe(false);
+    });
+
+    it("should return false for invalid characters", () => {
+      expect(validateHexColorFormat("#GGGGGG")).toBe(false);
+    });
+
+    it("should return false for empty string", () => {
+      expect(validateHexColorFormat("")).toBe(false);
+    });
+
+    it("should return false for random string", () => {
+      expect(validateHexColorFormat("invalid")).toBe(false);
+    });
+  });
+
+  describe("calculateComplementaryHexColor", () => {
+    it("should return inverse of black as white", () => {
+      const result = calculateComplementaryHexColor("#000000");
+      expect(result.toLowerCase()).toBe("#ffffff");
+    });
+
+    it("should return inverse of white as black", () => {
+      const result = calculateComplementaryHexColor("#ffffff");
+      expect(result.toLowerCase()).toBe("#000000");
+    });
+
+    it("should return cyan for red", () => {
+      const result = calculateComplementaryHexColor("#ff0000");
+      expect(result.toLowerCase()).toBe("#00ffff");
+    });
+
+    it("should handle hex without #", () => {
+      const result = calculateComplementaryHexColor("ff0000");
+      expect(result.toLowerCase()).toBe("#00ffff");
+    });
+  });
+
+  describe("adjustHexColorLightness", () => {
+    it("should lighten a color", () => {
+      const result = adjustHexColorLightness("#000000", 50);
+      expect(result).not.toBe("#000000");
+    });
+
+    it("should darken a color", () => {
+      const result = adjustHexColorLightness("#ffffff", -50);
+      expect(result).not.toBe("#ffffff");
+    });
+
+    it("should not exceed 100% lightness", () => {
+      const result = adjustHexColorLightness("#ffffff", 100);
+      // Should cap at white
+      expect(result.toLowerCase()).toBe("#ffffff");
+    });
+
+    it("should not go below 0% lightness", () => {
+      const result = adjustHexColorLightness("#000000", -100);
+      // Should cap at black
+      expect(result.toLowerCase()).toBe("#000000");
+    });
+  });
+
+  describe("parseHslStringToComponents", () => {
+    it("should parse valid HSL string", () => {
+      const result = parseHslStringToComponents("187 94% 43%");
+      expect(result).toEqual({hue: 187, saturation: 94, lightness: 43});
+    });
+
+    it("should parse HSL with zero values", () => {
+      const result = parseHslStringToComponents("0 0% 0%");
+      expect(result).toEqual({hue: 0, saturation: 0, lightness: 0});
+    });
+
+    it("should return null for invalid format", () => {
+      expect(parseHslStringToComponents("invalid")).toBeNull();
+    });
+
+    it("should return null for empty string", () => {
+      expect(parseHslStringToComponents("")).toBeNull();
+    });
+
+    it("should return null for partial HSL", () => {
+      expect(parseHslStringToComponents("187 94%")).toBeNull();
+    });
+  });
+});

package/src/lib/color-conversion-utilities.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Utility functions for color conversion and manipulation.
+ * Provides hex-to-HSL conversion and color validation for CSS custom properties.
+ * @module lib/color-conversion-utilities
+ */
+
+/**
+ * Converts a hexadecimal color code to an HSL string for CSS variables.
+ * The output format matches Tailwind CSS HSL variable format: "h s% l%"
+ *
+ * @param hexColor - Hex color code (e.g., "#06b6d4" or "06b6d4")
+ * @returns HSL values as "h s% l%" string suitable for CSS variables
+ *
+ * @example
+ * ```typescript
+ * convertHexToHslString("#06b6d4"); // "187 94% 43%"
+ * convertHexToHslString("#ec4899"); // "330 81% 60%"
+ * ```
+ */
+export function convertHexToHslString(hexColor: string): string {
+  // Remove # if present
+  const cleanHex = hexColor.replace("#", "");
+
+  // Parse RGB values
+  const r = Number.parseInt(cleanHex.slice(0, 2), 16) / 255;
+  const g = Number.parseInt(cleanHex.slice(2, 4), 16) / 255;
+  const b = Number.parseInt(cleanHex.slice(4, 6), 16) / 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;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+    // max is always r, g, or b - no default case needed
+    if (max === r) {
+      h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+    } else if (max === g) {
+      h = ((b - r) / d + 2) / 6;
+    } else {
+      h = ((r - g) / d + 4) / 6;
+    }
+  }
+
+  return `${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`;
+}
+
+/**
+ * Converts HSL color values to a hexadecimal color string.
+ *
+ * @param hue - Hue value (0-360)
+ * @param saturation - Saturation percentage (0-100)
+ * @param lightness - Lightness percentage (0-100)
+ * @returns Hex color code (e.g., "#06b6d4")
+ */
+export function convertHslToHexString(hue: number, saturation: number, lightness: number): string {
+  const sNorm = saturation / 100;
+  const lNorm = lightness / 100;
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm;
+  const x = c * (1 - Math.abs(((hue / 60) % 2) - 1));
+  const m = lNorm - c / 2;
+
+  const getRgb = (): [number, number, number] => {
+    if (hue >= 0 && hue < 60) return [c, x, 0];
+    if (hue >= 60 && hue < 120) return [x, c, 0];
+    if (hue >= 120 && hue < 180) return [0, c, x];
+    if (hue >= 180 && hue < 240) return [0, x, c];
+    if (hue >= 240 && hue < 300) return [x, 0, c];
+    return [c, 0, x];
+  };
+
+  const rgb = getRgb();
+
+  const toHex = (n: number) =>
+    Math.round((n + m) * 255)
+      .toString(16)
+      .padStart(2, "0");
+
+  return `#${toHex(rgb[0])}${toHex(rgb[1])}${toHex(rgb[2])}`;
+}
+
+/**
+ * Validates whether a string is a valid 6-digit hexadecimal color code.
+ *
+ * @param hexColor - String to validate
+ * @returns True if valid 6-digit hex color (with or without #)
+ *
+ * @example
+ * ```typescript
+ * validateHexColorFormat("#06b6d4"); // true
+ * validateHexColorFormat("06b6d4");  // true
+ * validateHexColorFormat("#FFF");    // false (3-digit not supported)
+ * validateHexColorFormat("invalid"); // false
+ * ```
+ */
+export function validateHexColorFormat(hexColor: string): boolean {
+  return /^#?[\dA-Fa-f]{6}$/u.test(hexColor);
+}
+
+/**
+ * Generates the complementary (inverse) color for a given hex color.
+ *
+ * @param hexColor - Hex color code
+ * @returns Complementary hex color code
+ */
+export function calculateComplementaryHexColor(hexColor: string): string {
+  const cleanHex = hexColor.replace("#", "");
+  const r = 255 - Number.parseInt(cleanHex.slice(0, 2), 16);
+  const g = 255 - Number.parseInt(cleanHex.slice(2, 4), 16);
+  const b = 255 - Number.parseInt(cleanHex.slice(4, 6), 16);
+
+  return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Adjusts the lightness of a hexadecimal color by a specified amount.
+ *
+ * @param hexColor - Hex color code
+ * @param lightnessAdjustment - Amount to adjust lightness (-100 to 100)
+ * @returns Adjusted hex color code
+ */
+export function adjustHexColorLightness(hexColor: string, lightnessAdjustment: number): string {
+  const hsl = convertHexToHslString(hexColor);
+  const [h, s, l] = hsl.split(" ").map((v, i) => (i === 0 ? Number.parseInt(v, 10) : Number.parseInt(v.replace("%", ""), 10)));
+
+  const newL = Math.max(0, Math.min(100, (l ?? 50) + lightnessAdjustment));
+  return convertHslToHexString(h ?? 0, s ?? 50, newL);
+}
+
+/**
+ * Parses an HSL CSS variable string into its numeric components.
+ *
+ * @param hslString - HSL string in format "h s% l%"
+ * @returns Object with hue, saturation, lightness values or null if invalid
+ */
+export function parseHslStringToComponents(hslString: string): {hue: number; saturation: number; lightness: number} | null {
+  const pattern = /^(?<hue>\d+)\s+(?<sat>\d+)%\s+(?<light>\d+)%$/u;
+  const match = pattern.exec(hslString);
+  if (!match?.groups) return null;
+
+  return {
+    hue: Number.parseInt(match.groups["hue"] ?? "0", 10),
+    saturation: Number.parseInt(match.groups["sat"] ?? "0", 10),
+    lightness: Number.parseInt(match.groups["light"] ?? "0", 10),
+  };
+}
+
+// Legacy aliases for backwards compatibility (deprecated)
+/** @deprecated Use convertHexToHslString instead */
+export const hexToHsl = convertHexToHslString;
+/** @deprecated Use convertHslToHexString instead */
+export const hslToHex = convertHslToHexString;
+/** @deprecated Use validateHexColorFormat instead */
+export const isValidHexColor = validateHexColorFormat;
+/** @deprecated Use calculateComplementaryHexColor instead */
+export const getComplementaryColor = calculateComplementaryHexColor;
+/** @deprecated Use adjustHexColorLightness instead */
+export const adjustLightness = adjustHexColorLightness;
+/** @deprecated Use parseHslStringToComponents instead */
+export const parseHslString = parseHslStringToComponents;

package/src/lib/utilities.test.ts

@@ -0,0 +1,37 @@
+import {describe, expect, it} from "vitest";
+import {cn} from "./utilities";
+
+describe("cn utility", () => {
+  it("should merge class names", () => {
+    expect(cn("class1", "class2")).toBe("class1 class2");
+  });
+
+  it("should handle conditional classes", () => {
+    expect(cn("class1", true && "class2", false && "class3")).toBe("class1 class2");
+  });
+
+  it("should handle null and undefined", () => {
+    expect(cn("class1", null, undefined)).toBe("class1");
+  });
+
+  it("should merge tailwind classes correctly", () => {
+    expect(cn("px-2", "px-4")).toBe("px-4");
+    expect(cn("text-red-500", "text-blue-500")).toBe("text-blue-500");
+  });
+
+  it("should handle arrays of classes", () => {
+    expect(cn(["class1", "class2"])).toBe("class1 class2");
+  });
+
+  it("should handle objects of classes", () => {
+    expect(cn({class1: true, class2: false, class3: true})).toBe("class1 class3");
+  });
+
+  it("should handle complex nested structures", () => {
+    expect(cn("base", ["nested1", {nested2: true}], {obj1: false, obj2: true})).toBe("base nested1 nested2 obj2");
+  });
+
+  it("should handle empty input", () => {
+    expect(cn()).toBe("");
+  });
+});