@proyecto-viviana/solid-stately 0.2.7 → 0.3.0

package/src/color/Color.ts

@@ -15,7 +15,7 @@ import type {
   RGBColor,
   HSLColor,
   HSBColor,
-} from './types';
+} from "./types";
 
 // Channel ranges
 const RGB_CHANNEL_RANGE: ColorChannelRange = {
@@ -48,28 +48,33 @@ const PERCENT_CHANNEL_RANGE: ColorChannelRange = {
 
 // Channel names (English only for now)
 const CHANNEL_NAMES: Record<ColorChannel, string> = {
-  hue: 'Hue',
-  saturation: 'Saturation',
-  brightness: 'Brightness',
-  lightness: 'Lightness',
-  red: 'Red',
-  green: 'Green',
-  blue: 'Blue',
-  alpha: 'Alpha',
+  hue: "Hue",
+  saturation: "Saturation",
+  brightness: "Brightness",
+  lightness: "Lightness",
+  red: "Red",
+  green: "Green",
+  blue: "Blue",
+  alpha: "Alpha",
 };
 
-// Hue names for color naming
-const HUE_NAMES: Array<{ max: number; name: string }> = [
-  { max: 15, name: 'pink' },
-  { max: 48, name: 'red' },
-  { max: 94, name: 'orange' },
-  { max: 135, name: 'yellow' },
-  { max: 175, name: 'green' },
-  { max: 264, name: 'cyan' },
-  { max: 284, name: 'blue' },
-  { max: 320, name: 'purple' },
-  { max: 349, name: 'magenta' },
-  { max: 360, name: 'pink' },
+// React Stately uses OKLCH for color names so that lightness is perceptually
+// consistent across hues.
+const ORANGE_LIGHTNESS_THRESHOLD = 0.68;
+const YELLOW_GREEN_LIGHTNESS_THRESHOLD = 0.85;
+const MAX_DARK_LIGHTNESS = 0.55;
+const GRAY_THRESHOLD = 0.001;
+const OKLCH_HUES: Array<[number, string]> = [
+  [0, "pink"],
+  [15, "red"],
+  [48, "orange"],
+  [94, "yellow"],
+  [135, "green"],
+  [175, "cyan"],
+  [264, "blue"],
+  [284, "purple"],
+  [320, "magenta"],
+  [349, "pink"],
 ];
 
 /**
@@ -252,79 +257,157 @@ function hsbToRgb(h: number, s: number, b: number): { r: number; g: number; b: n
   };
 }
 
-/**
- * Get hue name from hue angle.
- */
-function getHueNameFromAngle(hue: number): string {
-  for (const { max, name } of HUE_NAMES) {
-    if (hue <= max) {
-      return name;
+function getOklchHueName(l: number, c: number, h: number): [string, number] {
+  if (c < GRAY_THRESHOLD) {
+    return ["gray", l];
+  }
+
+  for (let i = 0; i < OKLCH_HUES.length; i += 1) {
+    let [hue, hueName] = OKLCH_HUES[i];
+    const [nextHue, nextHueName] = OKLCH_HUES[i + 1] || [360, "pink"];
+    if (h >= hue && h < nextHue) {
+      if (hueName === "orange") {
+        if (l < ORANGE_LIGHTNESS_THRESHOLD) {
+          hueName = "brown";
+        } else {
+          l = l - ORANGE_LIGHTNESS_THRESHOLD + MAX_DARK_LIGHTNESS;
+        }
+      }
+
+      if (h > hue + (nextHue - hue) / 2 && hueName !== nextHueName) {
+        hueName = `${hueName} ${nextHueName}`;
+      } else if (hueName === "yellow" && l < YELLOW_GREEN_LIGHTNESS_THRESHOLD) {
+        hueName = "yellow green";
+      }
+
+      return [hueName.toLocaleLowerCase(), l];
     }
   }
-  return 'pink';
+
+  return ["pink", l];
 }
 
-/**
- * Get a human-readable color name based on RGB values.
- */
-function getColorNameFromRgb(r: number, g: number, b: number, alpha: number): string {
-  // Convert to HSL for analysis
-  const { h, s, l } = rgbToHsl(r, g, b);
+function getColorNameFromColor(color: Color): string {
+  let [l, c, h] = toOKLCH(color);
+  const alpha = color.getChannelValue("alpha");
 
-  // Handle edge cases
-  if (l >= 100) {
-    return alpha < 1 ? `white ${Math.round(alpha * 100)}% transparent` : 'white';
+  if (l > 0.999) {
+    return alpha < 1 ? `white ${Math.round((1 - alpha) * 100)}% transparent` : "white";
   }
-  if (l <= 0) {
-    return alpha < 1 ? `black ${Math.round(alpha * 100)}% transparent` : 'black';
+
+  if (l < 0.001) {
+    return alpha < 1 ? `black ${Math.round((1 - alpha) * 100)}% transparent` : "black";
   }
 
-  // Build color name
-  const parts: string[] = [];
+  let hue: string;
+  [hue, l] = getOklchHueName(l, c, h);
 
-  // Lightness descriptor
-  if (l < 30) {
-    parts.push('very dark');
-  } else if (l < 55) {
-    parts.push('dark');
-  } else if (l > 85) {
-    parts.push('very light');
-  } else if (l > 70) {
-    parts.push('light');
+  let chroma = "";
+  if (c <= 0.1 && c >= GRAY_THRESHOLD) {
+    chroma = l >= 0.7 ? "pale" : "grayish";
+  } else if (c >= 0.15) {
+    chroma = "vibrant";
   }
 
-  // Saturation/chroma descriptor
-  if (s < 10) {
-    parts.push('gray');
-  } else if (s < 30) {
-    parts.push('grayish');
-  } else if (s > 80) {
-    parts.push('vibrant');
+  let lightness = "";
+  if (l < 0.3) {
+    lightness = "very dark";
+  } else if (l < MAX_DARK_LIGHTNESS) {
+    lightness = "dark";
+  } else if (l < 0.7) {
+    lightness = "";
+  } else if (l < 0.85) {
+    lightness = "light";
+  } else {
+    lightness = "very light";
   }
 
-  // Hue name (skip if gray)
-  if (s >= 10) {
-    let hueName = getHueNameFromAngle(h);
+  const name = [lightness, chroma, hue].filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+  if (alpha < 1) {
+    return `${Math.round((1 - alpha) * 100)}% transparent ${name}`.trim();
+  }
 
-    // Special cases
-    if (hueName === 'orange' && l < 68) {
-      hueName = 'brown';
-    }
-    if (hueName === 'yellow' && l < 85 && s > 50) {
-      hueName = 'yellow green';
-    }
+  return name;
+}
 
-    parts.push(hueName);
-  }
+function getHueNameFromColor(color: Color): string {
+  const [l, c, h] = toOKLCH(color);
+  const [name] = getOklchHueName(l, c, h);
+  return name;
+}
 
-  let name = parts.join(' ');
+function toOKLCH(color: Color): [number, number, number] {
+  const rgb = color.toFormat("rgb");
+  let red = rgb.getChannelValue("red") / 255;
+  let green = rgb.getChannelValue("green") / 255;
+  let blue = rgb.getChannelValue("blue") / 255;
+  [red, green, blue] = linSRGB(red, green, blue);
+  const [x, y, z] = linSRGBToXYZ(red, green, blue);
+  const [l, a, b] = xyzToOKLab(x, y, z);
+  return okLabToOKLCH(l, a, b);
+}
 
-  // Add transparency
-  if (alpha < 1) {
-    name += ` ${Math.round(alpha * 100)}% transparent`;
+function okLabToOKLCH(l: number, a: number, b: number): [number, number, number] {
+  const hue = (Math.atan2(b, a) * 180) / Math.PI;
+  return [l, Math.sqrt(a ** 2 + b ** 2), hue >= 0 ? hue : hue + 360];
+}
+
+function linSRGB(r: number, g: number, b: number): [number, number, number] {
+  return [linSRGBComponent(r), linSRGBComponent(g), linSRGBComponent(b)];
+}
+
+function linSRGBComponent(value: number) {
+  const sign = value < 0 ? -1 : 1;
+  const abs = Math.abs(value);
+
+  if (abs <= 0.04045) {
+    return value / 12.92;
   }
 
-  return name || 'color';
+  return sign * Math.pow((abs + 0.055) / 1.055, 2.4);
+}
+
+function linSRGBToXYZ(r: number, g: number, b: number): [number, number, number] {
+  const matrix = [
+    506752 / 1228815,
+    87881 / 245763,
+    12673 / 70218,
+    87098 / 409605,
+    175762 / 245763,
+    12673 / 175545,
+    7918 / 409605,
+    87881 / 737289,
+    1001167 / 1053270,
+  ];
+  return multiplyMatrix(matrix, r, g, b);
+}
+
+function xyzToOKLab(x: number, y: number, z: number): [number, number, number] {
+  const xyzToLMS = [
+    0.819022437996703, 0.3619062600528904, -0.1288737815209879, 0.0329836539323885,
+    0.9292868615863434, 0.0361446663506424, 0.0481771893596242, 0.2642395317527308,
+    0.6335478284694309,
+  ];
+  const lmsToOKLab = [
+    0.210454268309314, 0.7936177747023054, -0.0040720430116193, 1.9779985324311684,
+    -2.4285922420485799, 0.450593709617411, 0.0259040424655478, 0.7827717124575296,
+    -0.8086757549230774,
+  ];
+
+  const [a, b, c] = multiplyMatrix(xyzToLMS, x, y, z);
+  return multiplyMatrix(lmsToOKLab, Math.cbrt(a), Math.cbrt(b), Math.cbrt(c));
+}
+
+function multiplyMatrix(
+  matrix: number[],
+  x: number,
+  y: number,
+  z: number,
+): [number, number, number] {
+  const a = matrix[0] * x + matrix[1] * y + matrix[2] * z;
+  const b = matrix[3] * x + matrix[4] * y + matrix[5] * z;
+  const c = matrix[6] * x + matrix[7] * y + matrix[8] * z;
+  return [a, b, c];
 }
 
 /**
@@ -345,18 +428,18 @@ class RGBColorImpl implements Color {
 
   toFormat(format: ColorFormat): Color {
     switch (format) {
-      case 'hex':
-      case 'hexa':
-      case 'rgb':
-      case 'rgba':
+      case "hex":
+      case "hexa":
+      case "rgb":
+      case "rgba":
         return this.clone();
-      case 'hsl':
-      case 'hsla': {
+      case "hsl":
+      case "hsla": {
         const { h, s, l } = rgbToHsl(this.red, this.green, this.blue);
         return new HSLColorImpl(h, s, l, this.alpha);
       }
-      case 'hsb':
-      case 'hsba': {
+      case "hsb":
+      case "hsba": {
         const { h, s, b } = rgbToHsb(this.red, this.green, this.blue);
         return new HSBColorImpl(h, s, b, this.alpha);
       }
@@ -365,18 +448,22 @@ class RGBColorImpl implements Color {
     }
   }
 
-  toString(format?: ColorFormat | 'css'): string {
-    const f = format ?? 'css';
+  toString(format?: ColorFormat | "css"): string {
+    const f = format ?? "css";
 
     switch (f) {
-      case 'hex':
-        return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue.toString(16).padStart(2, '0')}`;
-      case 'hexa':
-        return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue.toString(16).padStart(2, '0')}${Math.round(this.alpha * 255).toString(16).padStart(2, '0')}`;
-      case 'rgb':
+      case "hex":
+        return `#${this.red.toString(16).padStart(2, "0")}${this.green.toString(16).padStart(2, "0")}${this.blue.toString(16).padStart(2, "0")}`;
+      case "hexa":
+        return `#${this.red.toString(16).padStart(2, "0")}${this.green.toString(16).padStart(2, "0")}${this.blue.toString(16).padStart(2, "0")}${Math.round(
+          this.alpha * 255,
+        )
+          .toString(16)
+          .padStart(2, "0")}`;
+      case "rgb":
         return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-      case 'rgba':
-      case 'css':
+      case "rgba":
+      case "css":
         return this.alpha === 1
           ? `rgb(${this.red}, ${this.green}, ${this.blue})`
           : `rgba(${this.red}, ${this.green}, ${this.blue}, ${this.alpha})`;
@@ -395,21 +482,21 @@ class RGBColorImpl implements Color {
 
   getChannelValue(channel: ColorChannel): number {
     switch (channel) {
-      case 'red':
+      case "red":
         return this.red;
-      case 'green':
+      case "green":
         return this.green;
-      case 'blue':
+      case "blue":
         return this.blue;
-      case 'alpha':
+      case "alpha":
         return this.alpha;
       // Cross-color-space channels - convert to HSB
-      case 'hue':
-      case 'saturation':
-      case 'brightness':
-        return this.toFormat('hsb').getChannelValue(channel);
-      case 'lightness':
-        return this.toFormat('hsl').getChannelValue(channel);
+      case "hue":
+      case "saturation":
+      case "brightness":
+        return this.toFormat("hsb").getChannelValue(channel);
+      case "lightness":
+        return this.toFormat("hsl").getChannelValue(channel);
       default:
         throw new Error(`Invalid channel: ${channel}`);
     }
@@ -417,21 +504,21 @@ class RGBColorImpl implements Color {
 
   withChannelValue(channel: ColorChannel, value: number): Color {
     switch (channel) {
-      case 'red':
+      case "red":
         return new RGBColorImpl(value, this.green, this.blue, this.alpha);
-      case 'green':
+      case "green":
         return new RGBColorImpl(this.red, value, this.blue, this.alpha);
-      case 'blue':
+      case "blue":
         return new RGBColorImpl(this.red, this.green, value, this.alpha);
-      case 'alpha':
+      case "alpha":
         return new RGBColorImpl(this.red, this.green, this.blue, value);
       // Cross-color-space channels - convert, update, convert back
-      case 'hue':
-      case 'saturation':
-      case 'brightness':
-        return this.toFormat('hsb').withChannelValue(channel, value).toFormat('rgb');
-      case 'lightness':
-        return this.toFormat('hsl').withChannelValue(channel, value).toFormat('rgb');
+      case "hue":
+      case "saturation":
+      case "brightness":
+        return this.toFormat("hsb").withChannelValue(channel, value).toFormat("rgb");
+      case "lightness":
+        return this.toFormat("hsl").withChannelValue(channel, value).toFormat("rgb");
       default:
         throw new Error(`Invalid channel: ${channel}`);
     }
@@ -439,17 +526,17 @@ class RGBColorImpl implements Color {
 
   getChannelRange(channel: ColorChannel): ColorChannelRange {
     switch (channel) {
-      case 'red':
-      case 'green':
-      case 'blue':
+      case "red":
+      case "green":
+      case "blue":
         return RGB_CHANNEL_RANGE;
-      case 'alpha':
+      case "alpha":
         return ALPHA_CHANNEL_RANGE;
-      case 'hue':
+      case "hue":
         return HUE_CHANNEL_RANGE;
-      case 'saturation':
-      case 'brightness':
-      case 'lightness':
+      case "saturation":
+      case "brightness":
+      case "lightness":
         return PERCENT_CHANNEL_RANGE;
       default:
         throw new Error(`Invalid channel: ${channel}`);
@@ -461,8 +548,8 @@ class RGBColorImpl implements Color {
   }
 
   getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions {
-    if (channel === 'alpha') {
-      return { style: 'percent' };
+    if (channel === "alpha") {
+      return { style: "percent" };
     }
     return { maximumFractionDigits: 0 };
   }
@@ -474,28 +561,27 @@ class RGBColorImpl implements Color {
   }
 
   getColorSpace(): ColorSpace {
-    return 'rgb';
+    return "rgb";
   }
 
   getColorSpaceAxes(xyChannels?: { xChannel?: ColorChannel; yChannel?: ColorChannel }): ColorAxes {
-    const xChannel = xyChannels?.xChannel ?? 'red';
-    const yChannel = xyChannels?.yChannel ?? 'green';
-    const channels: ColorChannel[] = ['red', 'green', 'blue'];
-    const zChannel = channels.find((c) => c !== xChannel && c !== yChannel) ?? 'blue';
+    const xChannel = xyChannels?.xChannel ?? "red";
+    const yChannel = xyChannels?.yChannel ?? "green";
+    const channels: ColorChannel[] = ["red", "green", "blue"];
+    const zChannel = channels.find((c) => c !== xChannel && c !== yChannel) ?? "blue";
     return { xChannel, yChannel, zChannel };
   }
 
   getColorChannels(): [ColorChannel, ColorChannel, ColorChannel] {
-    return ['red', 'green', 'blue'];
+    return ["red", "green", "blue"];
   }
 
-  getColorName(locale: string): string {
-    return getColorNameFromRgb(this.red, this.green, this.blue, this.alpha);
+  getColorName(_locale: string): string {
+    return getColorNameFromColor(this);
   }
 
   getHueName(_locale: string): string {
-    const { h } = rgbToHsl(this.red, this.green, this.blue);
-    return getHueNameFromAngle(h);
+    return getHueNameFromColor(this);
   }
 }
 
@@ -517,18 +603,18 @@ class HSLColorImpl implements Color {
 
   toFormat(format: ColorFormat): Color {
     switch (format) {
-      case 'hsl':
-      case 'hsla':
+      case "hsl":
+      case "hsla":
         return this.clone();
-      case 'hex':
-      case 'hexa':
-      case 'rgb':
-      case 'rgba': {
+      case "hex":
+      case "hexa":
+      case "rgb":
+      case "rgba": {
         const { r, g, b } = hslToRgb(this.hue, this.saturation, this.lightness);
         return new RGBColorImpl(r, g, b, this.alpha);
       }
-      case 'hsb':
-      case 'hsba': {
+      case "hsb":
+      case "hsba": {
         const { r, g, b } = hslToRgb(this.hue, this.saturation, this.lightness);
         const hsb = rgbToHsb(r, g, b);
         return new HSBColorImpl(hsb.h, hsb.s, hsb.b, this.alpha);
@@ -538,14 +624,14 @@ class HSLColorImpl implements Color {
     }
   }
 
-  toString(format?: ColorFormat | 'css'): string {
-    const f = format ?? 'css';
+  toString(format?: ColorFormat | "css"): string {
+    const f = format ?? "css";
 
     switch (f) {
-      case 'hsl':
+      case "hsl":
         return `hsl(${this.hue}, ${this.saturation}%, ${this.lightness}%)`;
-      case 'hsla':
-      case 'css':
+      case "hsla":
+      case "css":
         return this.alpha === 1
           ? `hsl(${this.hue}, ${this.saturation}%, ${this.lightness}%)`
           : `hsla(${this.hue}, ${this.saturation}%, ${this.lightness}%, ${this.alpha})`;
@@ -559,26 +645,26 @@ class HSLColorImpl implements Color {
   }
 
   toHexInt(): number {
-    return this.toFormat('rgb').toHexInt();
+    return this.toFormat("rgb").toHexInt();
   }
 
   getChannelValue(channel: ColorChannel): number {
     switch (channel) {
-      case 'hue':
+      case "hue":
         return this.hue;
-      case 'saturation':
+      case "saturation":
         return this.saturation;
-      case 'lightness':
+      case "lightness":
         return this.lightness;
-      case 'alpha':
+      case "alpha":
         return this.alpha;
       // Cross-color-space channels
-      case 'red':
-      case 'green':
-      case 'blue':
-        return this.toFormat('rgb').getChannelValue(channel);
-      case 'brightness':
-        return this.toFormat('hsb').getChannelValue(channel);
+      case "red":
+      case "green":
+      case "blue":
+        return this.toFormat("rgb").getChannelValue(channel);
+      case "brightness":
+        return this.toFormat("hsb").getChannelValue(channel);
       default:
         throw new Error(`Invalid channel: ${channel}`);
     }
@@ -586,21 +672,21 @@ class HSLColorImpl implements Color {
 
   withChannelValue(channel: ColorChannel, value: number): Color {
     switch (channel) {
-      case 'hue':
+      case "hue":
         return new HSLColorImpl(value, this.saturation, this.lightness, this.alpha);
-      case 'saturation':
+      case "saturation":
         return new HSLColorImpl(this.hue, value, this.lightness, this.alpha);
-      case 'lightness':
+      case "lightness":
         return new HSLColorImpl(this.hue, this.saturation, value, this.alpha);
-      case 'alpha':
+      case "alpha":
         return new HSLColorImpl(this.hue, this.saturation, this.lightness, value);
       // Cross-color-space channels
-      case 'red':
-      case 'green':
-      case 'blue':
-        return this.toFormat('rgb').withChannelValue(channel, value).toFormat('hsl');
-      case 'brightness':
-        return this.toFormat('hsb').withChannelValue(channel, value).toFormat('hsl');
+      case "red":
+      case "green":
+      case "blue":
+        return this.toFormat("rgb").withChannelValue(channel, value).toFormat("hsl");
+      case "brightness":
+        return this.toFormat("hsb").withChannelValue(channel, value).toFormat("hsl");
       default:
         throw new Error(`Invalid channel: ${channel}`);
     }
@@ -608,17 +694,17 @@ class HSLColorImpl implements Color {
 
   getChannelRange(channel: ColorChannel): ColorChannelRange {
     switch (channel) {
-      case 'hue':
+      case "hue":
         return HUE_CHANNEL_RANGE;
-      case 'saturation':
-      case 'lightness':
-      case 'brightness':
+      case "saturation":
+      case "lightness":
+      case "brightness":
         return PERCENT_CHANNEL_RANGE;
-      case 'alpha':
+      case "alpha":
         return ALPHA_CHANNEL_RANGE;
-      case 'red':
-      case 'green':
-      case 'blue':
+      case "red":
+      case "green":
+      case "blue":
         return RGB_CHANNEL_RANGE;
       default:
         throw new Error(`Invalid channel: ${channel}`);
@@ -630,47 +716,46 @@ class HSLColorImpl implements Color {
   }
 
   getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions {
-    if (channel === 'alpha') {
-      return { style: 'percent' };
+    if (channel === "alpha") {
+      return { style: "percent" };
     }
-    if (channel === 'hue') {
-      return { maximumFractionDigits: 0 };
+    if (channel === "hue") {
+      return { style: "unit", unit: "degree", unitDisplay: "narrow", maximumFractionDigits: 0 };
     }
-    return { style: 'percent', maximumFractionDigits: 0 };
+    return { style: "percent", maximumFractionDigits: 0 };
   }
 
   formatChannelValue(channel: ColorChannel, locale: string): string {
     const value = this.getChannelValue(channel);
     const options = this.getChannelFormatOptions(channel);
-    if (channel === 'saturation' || channel === 'lightness') {
+    if (channel === "saturation" || channel === "lightness") {
       return new Intl.NumberFormat(locale, options).format(value / 100);
     }
     return new Intl.NumberFormat(locale, options).format(value);
   }
 
   getColorSpace(): ColorSpace {
-    return 'hsl';
+    return "hsl";
   }
 
   getColorSpaceAxes(xyChannels?: { xChannel?: ColorChannel; yChannel?: ColorChannel }): ColorAxes {
-    const xChannel = xyChannels?.xChannel ?? 'saturation';
-    const yChannel = xyChannels?.yChannel ?? 'lightness';
-    const channels: ColorChannel[] = ['hue', 'saturation', 'lightness'];
-    const zChannel = channels.find((c) => c !== xChannel && c !== yChannel) ?? 'hue';
+    const xChannel = xyChannels?.xChannel ?? "saturation";
+    const yChannel = xyChannels?.yChannel ?? "lightness";
+    const channels: ColorChannel[] = ["hue", "saturation", "lightness"];
+    const zChannel = channels.find((c) => c !== xChannel && c !== yChannel) ?? "hue";
     return { xChannel, yChannel, zChannel };
   }
 
   getColorChannels(): [ColorChannel, ColorChannel, ColorChannel] {
-    return ['hue', 'saturation', 'lightness'];
+    return ["hue", "saturation", "lightness"];
   }
 
   getColorName(_locale: string): string {
-    const { r, g, b } = hslToRgb(this.hue, this.saturation, this.lightness);
-    return getColorNameFromRgb(r, g, b, this.alpha);
+    return getColorNameFromColor(this);
   }
 
   getHueName(_locale: string): string {
-    return getHueNameFromAngle(this.hue);
+    return getHueNameFromColor(this);
   }
 }
 
@@ -692,18 +777,18 @@ class HSBColorImpl implements Color {
 
   toFormat(format: ColorFormat): Color {
     switch (format) {
-      case 'hsb':
-      case 'hsba':
+      case "hsb":
+      case "hsba":
         return this.clone();
-      case 'hex':
-      case 'hexa':
-      case 'rgb':
-      case 'rgba': {
+      case "hex":
+      case "hexa":
+      case "rgb":
+      case "rgba": {
         const { r, g, b } = hsbToRgb(this.hue, this.saturation, this.brightness);
         return new RGBColorImpl(r, g, b, this.alpha);
       }
-      case 'hsl':
-      case 'hsla': {
+      case "hsl":
+      case "hsla": {
         const { r, g, b } = hsbToRgb(this.hue, this.saturation, this.brightness);
         const hsl = rgbToHsl(r, g, b);
         return new HSLColorImpl(hsl.h, hsl.s, hsl.l, this.alpha);
@@ -713,16 +798,16 @@ class HSBColorImpl implements Color {
     }
   }
 
-  toString(format?: ColorFormat | 'css'): string {
-    const f = format ?? 'css';
+  toString(format?: ColorFormat | "css"): string {
+    const f = format ?? "css";
 
     switch (f) {
-      case 'hsb':
+      case "hsb":
         return `hsb(${this.hue}, ${this.saturation}%, ${this.brightness}%)`;
-      case 'hsba':
-      case 'css':
+      case "hsba":
+      case "css":
         // HSB is not a standard CSS format, convert to RGB
-        return this.toFormat('rgba').toString('css');
+        return this.toFormat("rgba").toString("css");
       default:
         return this.toFormat(f as ColorFormat).toString(f);
     }
@@ -733,26 +818,26 @@ class HSBColorImpl implements Color {
   }
 
   toHexInt(): number {
-    return this.toFormat('rgb').toHexInt();
+    return this.toFormat("rgb").toHexInt();
   }
 
   getChannelValue(channel: ColorChannel): number {
     switch (channel) {
-      case 'hue':
+      case "hue":
         return this.hue;
-      case 'saturation':
+      case "saturation":
         return this.saturation;
-      case 'brightness':
+      case "brightness":
         return this.brightness;
-      case 'alpha':
+      case "alpha":
         return this.alpha;
       // Cross-color-space channels
-      case 'red':
-      case 'green':
-      case 'blue':
-        return this.toFormat('rgb').getChannelValue(channel);
-      case 'lightness':
-        return this.toFormat('hsl').getChannelValue(channel);
+      case "red":
+      case "green":
+      case "blue":
+        return this.toFormat("rgb").getChannelValue(channel);
+      case "lightness":
+        return this.toFormat("hsl").getChannelValue(channel);
       default:
         throw new Error(`Invalid channel: ${channel}`);
     }
@@ -760,21 +845,21 @@ class HSBColorImpl implements Color {
 
   withChannelValue(channel: ColorChannel, value: number): Color {
     switch (channel) {
-      case 'hue':
+      case "hue":
         return new HSBColorImpl(value, this.saturation, this.brightness, this.alpha);
-      case 'saturation':
+      case "saturation":
         return new HSBColorImpl(this.hue, value, this.brightness, this.alpha);
-      case 'brightness':
+      case "brightness":
         return new HSBColorImpl(this.hue, this.saturation, value, this.alpha);
-      case 'alpha':
+      case "alpha":
         return new HSBColorImpl(this.hue, this.saturation, this.brightness, value);
       // Cross-color-space channels
-      case 'red':
-      case 'green':
-      case 'blue':
-        return this.toFormat('rgb').withChannelValue(channel, value).toFormat('hsb');
-      case 'lightness':
-        return this.toFormat('hsl').withChannelValue(channel, value).toFormat('hsb');
+      case "red":
+      case "green":
+      case "blue":
+        return this.toFormat("rgb").withChannelValue(channel, value).toFormat("hsb");
+      case "lightness":
+        return this.toFormat("hsl").withChannelValue(channel, value).toFormat("hsb");
       default:
         throw new Error(`Invalid channel: ${channel}`);
     }
@@ -782,17 +867,17 @@ class HSBColorImpl implements Color {
 
   getChannelRange(channel: ColorChannel): ColorChannelRange {
     switch (channel) {
-      case 'hue':
+      case "hue":
         return HUE_CHANNEL_RANGE;
-      case 'saturation':
-      case 'brightness':
-      case 'lightness':
+      case "saturation":
+      case "brightness":
+      case "lightness":
         return PERCENT_CHANNEL_RANGE;
-      case 'alpha':
+      case "alpha":
         return ALPHA_CHANNEL_RANGE;
-      case 'red':
-      case 'green':
-      case 'blue':
+      case "red":
+      case "green":
+      case "blue":
         return RGB_CHANNEL_RANGE;
       default:
         throw new Error(`Invalid channel: ${channel}`);
@@ -804,47 +889,46 @@ class HSBColorImpl implements Color {
   }
 
   getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions {
-    if (channel === 'alpha') {
-      return { style: 'percent' };
+    if (channel === "alpha") {
+      return { style: "percent" };
     }
-    if (channel === 'hue') {
-      return { maximumFractionDigits: 0 };
+    if (channel === "hue") {
+      return { style: "unit", unit: "degree", unitDisplay: "narrow", maximumFractionDigits: 0 };
     }
-    return { style: 'percent', maximumFractionDigits: 0 };
+    return { style: "percent", maximumFractionDigits: 0 };
   }
 
   formatChannelValue(channel: ColorChannel, locale: string): string {
     const value = this.getChannelValue(channel);
     const options = this.getChannelFormatOptions(channel);
-    if (channel === 'saturation' || channel === 'brightness') {
+    if (channel === "saturation" || channel === "brightness") {
       return new Intl.NumberFormat(locale, options).format(value / 100);
     }
     return new Intl.NumberFormat(locale, options).format(value);
   }
 
   getColorSpace(): ColorSpace {
-    return 'hsb';
+    return "hsb";
   }
 
   getColorSpaceAxes(xyChannels?: { xChannel?: ColorChannel; yChannel?: ColorChannel }): ColorAxes {
-    const xChannel = xyChannels?.xChannel ?? 'saturation';
-    const yChannel = xyChannels?.yChannel ?? 'brightness';
-    const channels: ColorChannel[] = ['hue', 'saturation', 'brightness'];
-    const zChannel = channels.find((c) => c !== xChannel && c !== yChannel) ?? 'hue';
+    const xChannel = xyChannels?.xChannel ?? "saturation";
+    const yChannel = xyChannels?.yChannel ?? "brightness";
+    const channels: ColorChannel[] = ["hue", "saturation", "brightness"];
+    const zChannel = channels.find((c) => c !== xChannel && c !== yChannel) ?? "hue";
     return { xChannel, yChannel, zChannel };
   }
 
   getColorChannels(): [ColorChannel, ColorChannel, ColorChannel] {
-    return ['hue', 'saturation', 'brightness'];
+    return ["hue", "saturation", "brightness"];
   }
 
   getColorName(_locale: string): string {
-    const { r, g, b } = hsbToRgb(this.hue, this.saturation, this.brightness);
-    return getColorNameFromRgb(r, g, b, this.alpha);
+    return getColorNameFromColor(this);
   }
 
   getHueName(_locale: string): string {
-    return getHueNameFromAngle(this.hue);
+    return getHueNameFromColor(this);
   }
 }
 
@@ -855,8 +939,11 @@ export function parseColor(value: string): Color {
   const trimmed = value.trim().toLowerCase();
 
   // Hex format
-  if (trimmed.startsWith('#')) {
+  if (trimmed.startsWith("#")) {
     const hex = trimmed.slice(1);
+    if (!/^[0-9a-f]+$/i.test(hex)) {
+      throw new Error(`Invalid hex color: ${value}`);
+    }
     if (hex.length === 3) {
       const r = parseInt(hex[0] + hex[0], 16);
       const g = parseInt(hex[1] + hex[1], 16);
@@ -887,7 +974,9 @@ export function parseColor(value: string): Color {
   }
 
   // RGB/RGBA format
-  const rgbMatch = trimmed.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)$/);
+  const rgbMatch = trimmed.match(
+    /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)$/,
+  );
   if (rgbMatch) {
     const r = parseInt(rgbMatch[1], 10);
     const g = parseInt(rgbMatch[2], 10);
@@ -897,7 +986,9 @@ export function parseColor(value: string): Color {
   }
 
   // HSL/HSLA format
-  const hslMatch = trimmed.match(/^hsla?\(\s*(\d+)\s*,\s*(\d+)%\s*,\s*(\d+)%\s*(?:,\s*([\d.]+))?\s*\)$/);
+  const hslMatch = trimmed.match(
+    /^hsla?\(\s*(\d+)\s*,\s*(\d+)%\s*,\s*(\d+)%\s*(?:,\s*([\d.]+))?\s*\)$/,
+  );
   if (hslMatch) {
     const h = parseInt(hslMatch[1], 10);
     const s = parseInt(hslMatch[2], 10);
@@ -907,7 +998,9 @@ export function parseColor(value: string): Color {
   }
 
   // HSB/HSBA format
-  const hsbMatch = trimmed.match(/^hsba?\(\s*(\d+)\s*,\s*(\d+)%\s*,\s*(\d+)%\s*(?:,\s*([\d.]+))?\s*\)$/);
+  const hsbMatch = trimmed.match(
+    /^hsba?\(\s*(\d+)\s*,\s*(\d+)%\s*,\s*(\d+)%\s*(?:,\s*([\d.]+))?\s*\)$/,
+  );
   if (hsbMatch) {
     const h = parseInt(hsbMatch[1], 10);
     const s = parseInt(hsbMatch[2], 10);
@@ -929,14 +1022,24 @@ export function createRGBColor(red: number, green: number, blue: number, alpha:
 /**
  * Create an HSL color.
  */
-export function createHSLColor(hue: number, saturation: number, lightness: number, alpha: number = 1): Color {
+export function createHSLColor(
+  hue: number,
+  saturation: number,
+  lightness: number,
+  alpha: number = 1,
+): Color {
   return new HSLColorImpl(hue, saturation, lightness, alpha);
 }
 
 /**
  * Create an HSB color.
  */
-export function createHSBColor(hue: number, saturation: number, brightness: number, alpha: number = 1): Color {
+export function createHSBColor(
+  hue: number,
+  saturation: number,
+  brightness: number,
+  alpha: number = 1,
+): Color {
   return new HSBColorImpl(hue, saturation, brightness, alpha);
 }
 
@@ -944,7 +1047,7 @@ export function createHSBColor(hue: number, saturation: number, brightness: numb
  * Normalize a color value (string or Color) to a Color object.
  */
 export function normalizeColor(value: string | Color): Color {
-  if (typeof value === 'string') {
+  if (typeof value === "string") {
     return parseColor(value);
   }
   return value;