reka-ui 2.8.0 → 2.9.0

package/src/shared/color/gradient.ts

@@ -0,0 +1,347 @@
+import type { Color, ColorChannel, ColorSpace, RGBColor } from './types'
+import { colorToString, convertToHsb, convertToHsl, convertToRgb } from './convert'
+
+/**
+ * Generates a CSS gradient for a color slider track.
+ */
+export function getSliderGradient(
+  color: Color,
+  channel: ColorChannel,
+  colorSpace: ColorSpace = color.space as ColorSpace,
+): string {
+  const hsl = convertToHsl(color)
+  const hsb = convertToHsb(color)
+
+  switch (channel) {
+    case 'hue':
+      return getHueGradient()
+    case 'saturation':
+      return getSaturationGradient(hsl, colorSpace)
+    case 'lightness':
+      return getLightnessGradient(hsl)
+    case 'brightness':
+      return getBrightnessGradient(hsb)
+    case 'red':
+      return getRedGradient(color)
+    case 'green':
+      return getGreenGradient(color)
+    case 'blue':
+      return getBlueGradient(color)
+    case 'alpha':
+      return getAlphaGradient(color)
+    default:
+      return ''
+  }
+}
+
+/**
+ * Generates a CSS gradient for a color area (2D picker).
+ */
+export function getAreaGradient(
+  color: Color,
+  xChannel: ColorChannel,
+  yChannel: ColorChannel,
+  colorSpace: ColorSpace = color.space as ColorSpace,
+): { background: string, gradientX: string, gradientY: string } {
+  const hsl = convertToHsl(color)
+  const hsb = convertToHsb(color)
+
+  // Determine which gradient layers to apply based on channels
+  const gradientX = getChannelGradientForArea(color, xChannel, colorSpace, 'x')
+  const gradientY = getChannelGradientForArea(color, yChannel, colorSpace, 'y')
+
+  // Background is the color with both channels at max
+  const bgColor = getAreaBackgroundColor(color, xChannel, yChannel, colorSpace)
+
+  return {
+    background: bgColor,
+    gradientX,
+    gradientY,
+  }
+}
+
+function getHueGradient(): string {
+  return 'linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000)'
+}
+
+function getSaturationGradient(hsl: { h: number, s: number, l: number, alpha: number }, colorSpace: ColorSpace): string {
+  const start = colorToString({ space: 'hsl', h: hsl.h, s: 0, l: colorSpace === 'hsl' ? hsl.l : 50, alpha: 1 }, 'hsl')
+  const end = colorToString({ space: 'hsl', h: hsl.h, s: 100, l: colorSpace === 'hsl' ? hsl.l : 50, alpha: 1 }, 'hsl')
+  return `linear-gradient(to right, ${start}, ${end})`
+}
+
+function getLightnessGradient(hsl: { h: number, s: number, l: number, alpha: number }): string {
+  const start = colorToString({ space: 'hsl', h: hsl.h, s: hsl.s, l: 0, alpha: 1 }, 'hsl')
+  const mid = colorToString({ space: 'hsl', h: hsl.h, s: hsl.s, l: 50, alpha: 1 }, 'hsl')
+  const end = colorToString({ space: 'hsl', h: hsl.h, s: hsl.s, l: 100, alpha: 1 }, 'hsl')
+  return `linear-gradient(to right, ${start}, ${mid}, ${end})`
+}
+
+function getBrightnessGradient(hsb: { h: number, s: number, b: number, alpha: number }): string {
+  const start = colorToString({ space: 'hsb', h: hsb.h, s: hsb.s, b: 0, alpha: 1 }, 'rgb')
+  const end = colorToString({ space: 'hsb', h: hsb.h, s: hsb.s, b: 100, alpha: 1 }, 'rgb')
+  return `linear-gradient(to right, ${start}, ${end})`
+}
+
+function getRedGradient(color: Color): string {
+  const { g, b, alpha } = color.space === 'rgb' ? color : { g: 128, b: 128, alpha: 1 }
+  const start = colorToString({ space: 'rgb', r: 0, g, b, alpha: 1 }, 'rgb')
+  const end = colorToString({ space: 'rgb', r: 255, g, b, alpha: 1 }, 'rgb')
+  return `linear-gradient(to right, ${start}, ${end})`
+}
+
+function getGreenGradient(color: Color): string {
+  const { r, b, alpha } = color.space === 'rgb' ? color : { r: 128, b: 128, alpha: 1 }
+  const start = colorToString({ space: 'rgb', r, g: 0, b, alpha: 1 }, 'rgb')
+  const end = colorToString({ space: 'rgb', r, g: 255, b, alpha: 1 }, 'rgb')
+  return `linear-gradient(to right, ${start}, ${end})`
+}
+
+function getBlueGradient(color: Color): string {
+  const { r, g, alpha } = color.space === 'rgb' ? color : { r: 128, g: 128, alpha: 1 }
+  const start = colorToString({ space: 'rgb', r, g, b: 0, alpha: 1 }, 'rgb')
+  const end = colorToString({ space: 'rgb', r, g, b: 255, alpha: 1 }, 'rgb')
+  return `linear-gradient(to right, ${start}, ${end})`
+}
+
+// Checkerboard pattern used behind alpha gradients to visualize transparency
+const CHECKERBOARD_LAYERS = [
+  'linear-gradient(45deg, #ccc 25%, transparent 25%)',
+  'linear-gradient(-45deg, #ccc 25%, transparent 25%)',
+  'linear-gradient(45deg, transparent 75%, #ccc 75%)',
+  'linear-gradient(-45deg, transparent 75%, #ccc 75%)',
+].join(', ')
+
+function getAlphaGradient(color: Color): string {
+  const { r, g, b } = color.space === 'rgb' ? color : convertToRgb(color)
+  const solidRgb = `rgb(${Math.round(r)}, ${Math.round(g)}, ${Math.round(b)})`
+  return `linear-gradient(to right, transparent, ${solidRgb}), ${CHECKERBOARD_LAYERS}`
+}
+
+function getChannelGradientForArea(
+  color: Color,
+  channel: ColorChannel,
+  colorSpace: ColorSpace,
+  axis: 'x' | 'y',
+): string {
+  const direction = axis === 'x' ? 'to right' : 'to top'
+  const hsl = convertToHsl(color)
+  const hsb = convertToHsb(color)
+
+  switch (channel) {
+    case 'saturation': {
+      if (colorSpace === 'hsb') {
+        // For HSB: White to transparent (overlay on pure hue)
+        // Left side (0% sat) = white, Right side (100% sat) = transparent (shows pure hue)
+        return `linear-gradient(${direction}, rgba(255, 255, 255, 1), rgba(255, 255, 255, 0))`
+      }
+      // For HSL: White to full color
+      const fullColor = colorToString({ space: 'hsl', h: hsl.h, s: 100, l: 50, alpha: 1 }, 'rgb')
+      return `linear-gradient(${direction}, #ffffff, ${fullColor})`
+    }
+    case 'lightness': {
+      // White -> color -> black
+      const mid = colorToString({ space: 'hsl', h: hsl.h, s: hsl.s, l: 50, alpha: 1 }, 'rgb')
+      return `linear-gradient(${direction}, #000000, ${mid}, #ffffff)`
+    }
+    case 'brightness': {
+      // For HSB: Transparent to black (overlay on pure hue)
+      // Top (100% brightness) = transparent (shows pure hue), Bottom (0% brightness) = black
+      return `linear-gradient(${direction}, rgba(0, 0, 0, 0), rgba(0, 0, 0, 1))`
+    }
+    default:
+      return ''
+  }
+}
+
+function getAreaBackgroundColor(
+  color: Color,
+  xChannel: ColorChannel,
+  yChannel: ColorChannel,
+  colorSpace: ColorSpace,
+): string {
+  const hsl = convertToHsl(color)
+  const hsb = convertToHsb(color)
+
+  // For HSL saturation/lightness area, show pure hue
+  if (colorSpace === 'hsl' && xChannel === 'saturation' && yChannel === 'lightness') {
+    return colorToString({ space: 'hsl', h: hsl.h, s: 100, l: 50, alpha: 1 }, 'rgb')
+  }
+
+  // For HSB saturation/brightness area, show pure hue
+  if (colorSpace === 'hsb' && xChannel === 'saturation' && yChannel === 'brightness') {
+    return colorToString({ space: 'hsb', h: hsb.h, s: 100, b: 100, alpha: 1 }, 'rgb')
+  }
+
+  // Default to white
+  return '#ffffff'
+}
+
+/**
+ * Gets the CSS background style for a color area.
+ */
+export function getAreaBackgroundStyle(
+  color: Color,
+  xChannel: ColorChannel,
+  yChannel: ColorChannel,
+  colorSpace: ColorSpace = color.space as ColorSpace,
+): Record<string, string> {
+  const hsl = convertToHsl(color)
+  const hsb = convertToHsb(color)
+
+  // Hue-based color picker (Hue/Saturation, Hue/Lightness, Hue/Brightness)
+  // Shows full rainbow spectrum horizontally
+  if (xChannel === 'hue') {
+    // Full hue gradient as background (rainbow spectrum)
+    const hueGradient = 'linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000)'
+
+    if (yChannel === 'saturation') {
+      // Vertical: gray at bottom (0% sat) fading to transparent at top (100% sat shows hue)
+      // No blend mode needed — transparent stacking is correct
+      const desatColor = colorToString({ space: 'hsl', h: hsl.h, s: 0, l: hsl.l, alpha: 1 }, 'rgb')
+      return {
+        backgroundImage: `linear-gradient(to bottom, transparent, ${desatColor}), ${hueGradient}`,
+      }
+    }
+
+    if (yChannel === 'lightness') {
+      // Vertical: black at bottom (L=0) → transparent at middle (L=50, shows hue) → white at top (L=100)
+      return {
+        backgroundImage: `linear-gradient(to top, #000000, transparent, #ffffff), ${hueGradient}`,
+      }
+    }
+
+    if (yChannel === 'brightness') {
+      // Vertical: black at bottom (B=0) → transparent at top (B=100, shows hue)
+      return {
+        backgroundImage: `linear-gradient(to top, #000000, transparent), ${hueGradient}`,
+      }
+    }
+  }
+
+  // Classic color picker gradients for saturation-based pickers
+  if (xChannel === 'saturation' && (yChannel === 'lightness' || yChannel === 'brightness')) {
+    if (colorSpace === 'hsl') {
+      // HSL: Base is pure hue at 50% lightness
+      // Saturation x-axis: gray (S=0) at left fading to transparent (shows pure hue at S=100)
+      // Lightness y-axis: black at bottom (L=0), transparent at middle (L=50), white at top (L=100)
+      const hueColor = colorToString({ space: 'hsl', h: hsl.h, s: 100, l: 50, alpha: 1 }, 'rgb')
+      const grayColor = colorToString({ space: 'hsl', h: hsl.h, s: 0, l: 50, alpha: 1 }, 'rgb')
+      const satGradient = `linear-gradient(to right, ${grayColor}, transparent)`
+      const lightGradient = `linear-gradient(to top, #000000, transparent, #ffffff)`
+
+      return {
+        backgroundColor: hueColor,
+        backgroundImage: `${lightGradient}, ${satGradient}`,
+      }
+    }
+
+    if (colorSpace === 'hsb') {
+      // HSB: Base is pure hue (full sat, full brightness)
+      // Top edge: white (0% sat) → pure hue (100% sat)
+      // Bottom edge: always black (0% brightness)
+      const hueColor = colorToString({ space: 'hsb', h: hsb.h, s: 100, b: 100, alpha: 1 }, 'rgb')
+      // White to transparent (left to right)
+      const satGradient = `linear-gradient(to right, #ffffff, transparent)`
+      // Black gradient from bottom up
+      const brightGradient = `linear-gradient(to top, #000000, transparent)`
+
+      return {
+        backgroundColor: hueColor,
+        backgroundImage: `${brightGradient}, ${satGradient}`,
+      }
+    }
+  }
+
+  // RGB color picker (Red/Green, Red/Blue, Green/Blue)
+  // Uses screen blend mode to combine gradients additively (like React Spectrum)
+  // Formula: 1 - (1 - a) * (1 - b), effectively adds RGB values
+  if (colorSpace === 'rgb'
+    && (xChannel === 'red' || xChannel === 'green' || xChannel === 'blue')
+    && (yChannel === 'red' || yChannel === 'green' || yChannel === 'blue')) {
+    const rgb = convertToRgb(color)
+
+    // Get the constant channel (z-channel - the one NOT x or y)
+    const allChannels = ['red', 'green', 'blue'] as const
+    const varyingChannels = [xChannel, yChannel]
+    const constantChannel = allChannels.find(c => !varyingChannels.includes(c))!
+    const constantValue = rgb[constantChannel === 'red' ? 'r' : constantChannel === 'green' ? 'g' : 'b']
+
+    // Create the three layers for screen blend mode:
+    // 1. X gradient: black to full-X-color
+    // 2. Y gradient: black to full-Y-color
+    // 3. Background: black with Z channel set
+
+    // X gradient: black (0,0,0) → full X (255,0,0) for red, etc.
+    const xColorStart: RGBColor = { space: 'rgb', r: 0, g: 0, b: 0, alpha: 1 }
+    const xColorEnd: RGBColor = {
+      space: 'rgb',
+      r: xChannel === 'red' ? 255 : 0,
+      g: xChannel === 'green' ? 255 : 0,
+      b: xChannel === 'blue' ? 255 : 0,
+      alpha: 1,
+    }
+    const xGradient = `linear-gradient(to right, ${colorToString(xColorStart, 'rgb')}, ${colorToString(xColorEnd, 'rgb')})`
+
+    // Y gradient: black (0,0,0) → full Y (0,255,0) for green, etc.
+    const yColorEnd: RGBColor = {
+      space: 'rgb',
+      r: yChannel === 'red' ? 255 : 0,
+      g: yChannel === 'green' ? 255 : 0,
+      b: yChannel === 'blue' ? 255 : 0,
+      alpha: 1,
+    }
+    const yGradient = `linear-gradient(to top, ${colorToString(xColorStart, 'rgb')}, ${colorToString(yColorEnd, 'rgb')})`
+
+    // Background: black with constant Z channel value
+    const bgColor: RGBColor = {
+      space: 'rgb',
+      r: constantChannel === 'red' ? constantValue : 0,
+      g: constantChannel === 'green' ? constantValue : 0,
+      b: constantChannel === 'blue' ? constantValue : 0,
+      alpha: 1,
+    }
+
+    return {
+      backgroundColor: colorToString(bgColor, 'rgb'),
+      backgroundImage: `${yGradient}, ${xGradient}`,
+      backgroundBlendMode: 'screen',
+    }
+  }
+
+  // Fallback for other combinations
+  const { background, gradientX, gradientY } = getAreaGradient(color, xChannel, yChannel, colorSpace)
+  const gradients: string[] = []
+  if (gradientY)
+    gradients.push(gradientY)
+  if (gradientX)
+    gradients.push(gradientX)
+
+  return {
+    backgroundColor: background,
+    backgroundImage: gradients.join(', '),
+  }
+}
+
+/**
+ * Gets the CSS background for a slider track.
+ */
+export function getSliderBackgroundStyle(
+  color: Color,
+  channel: ColorChannel,
+  colorSpace: ColorSpace = color.space as ColorSpace,
+): Record<string, string> {
+  const gradient = getSliderGradient(color, channel, colorSpace)
+
+  if (channel === 'alpha') {
+    return {
+      background: gradient,
+      backgroundSize: '100% 100%, 8px 8px, 8px 8px, 8px 8px, 8px 8px',
+      backgroundPosition: '0 0, 0 0, 0 4px, 4px -4px, -4px 0px',
+    }
+  }
+
+  return {
+    background: gradient,
+  }
+}

package/src/shared/color/index.ts

@@ -0,0 +1,35 @@
+// Channel operations
+export { getChannelName, getChannelRange, getChannelValue, setChannelValue, setChannelValues } from './channel'
+
+// Conversion
+export {
+  colorToHex,
+  colorToHsb,
+  colorToHsl,
+  colorToRgb,
+  colorToString,
+  convertToHsb,
+  convertToHsl,
+  convertToRgb,
+} from './convert'
+
+// Gradients
+export { getAreaBackgroundStyle, getAreaGradient, getSliderBackgroundStyle, getSliderGradient } from './gradient'
+
+// Parsing
+export { isValidColor, normalizeColor, parseColor } from './parse'
+
+// Types
+export type {
+  ChannelRange,
+  Color,
+  ColorChannel,
+  ColorFormat,
+  ColorSpace,
+  HSBColor,
+  HSLColor,
+  RGBColor,
+} from './types'
+
+// Legacy utilities (keeping for backwards compatibility)
+export { getColorContrast, getColorName, hexToHSL, hexToRGB } from './utils'

package/src/shared/color/parse.ts

@@ -0,0 +1,140 @@
+import type { Color, HSBColor, HSLColor, RGBColor } from './types'
+
+/**
+ * Parses a color string into a Color object.
+ * Supports hex (#rrggbb, #rgb), rgb(), hsl(), and hsb()/hsv() formats.
+ */
+export function parseColor(value: string): Color {
+  const trimmed = value.trim().toLowerCase()
+
+  // Hex format
+  if (trimmed.startsWith('#')) {
+    return parseHex(trimmed)
+  }
+
+  // rgb() format
+  if (trimmed.startsWith('rgb')) {
+    return parseRgb(trimmed)
+  }
+
+  // hsl() format
+  if (trimmed.startsWith('hsl')) {
+    return parseHsl(trimmed)
+  }
+
+  // hsb() or hsv() format
+  if (trimmed.startsWith('hsb') || trimmed.startsWith('hsv')) {
+    return parseHsb(trimmed)
+  }
+
+  throw new Error(`Unable to parse color: ${value}`)
+}
+
+function parseHex(hex: string): RGBColor {
+  let normalized = hex.slice(1)
+
+  // Validate hex format (3, 6, or 8 hex digits)
+  if (!/^[0-9A-F]{3}$/i.test(normalized) && !/^[0-9A-F]{6}$/i.test(normalized) && !/^[0-9A-F]{8}$/i.test(normalized)) {
+    throw new Error(`Invalid hex color: ${hex}. Expected format: #RGB, #RRGGBB, or #RRGGBBAA`)
+  }
+
+  // Expand shorthand (e.g., #f00 -> #ff0000)
+  if (normalized.length === 3) {
+    normalized = normalized.split('').map(c => c + c).join('')
+  }
+
+  // Handle 6-digit hex
+  if (normalized.length === 6) {
+    const bigint = parseInt(normalized, 16)
+    return {
+      space: 'rgb',
+      r: (bigint >> 16) & 255,
+      g: (bigint >> 8) & 255,
+      b: bigint & 255,
+      alpha: 1,
+    }
+  }
+
+  // Handle 8-digit hex (with alpha)
+  if (normalized.length === 8) {
+    const bigint = parseInt(normalized, 16)
+    return {
+      space: 'rgb',
+      r: (bigint >> 24) & 255,
+      g: (bigint >> 16) & 255,
+      b: (bigint >> 8) & 255,
+      alpha: (bigint & 255) / 255,
+    }
+  }
+
+  throw new Error(`Invalid hex color: ${hex}`)
+}
+
+function parseRgb(rgb: string): RGBColor {
+  const match = rgb.match(/rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)/)
+  if (!match) {
+    throw new Error(`Invalid RGB color: ${rgb}`)
+  }
+
+  return {
+    space: 'rgb',
+    r: parseFloat(match[1]),
+    g: parseFloat(match[2]),
+    b: parseFloat(match[3]),
+    alpha: match[4] ? parseFloat(match[4]) : 1,
+  }
+}
+
+function parseHsl(hsl: string): HSLColor {
+  const match = hsl.match(/hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*(?:,\s*([\d.]+)\s*)?\)/)
+  if (!match) {
+    throw new Error(`Invalid HSL color: ${hsl}`)
+  }
+
+  return {
+    space: 'hsl',
+    h: parseFloat(match[1]),
+    s: parseFloat(match[2]),
+    l: parseFloat(match[3]),
+    alpha: match[4] ? parseFloat(match[4]) : 1,
+  }
+}
+
+function parseHsb(hsb: string): HSBColor {
+  const match = hsb.match(/hsb[av]?\(\s*([\d.]+)\s*,\s*([\d.]+)%?\s*,\s*([\d.]+)%?\s*(?:,\s*([\d.]+)\s*)?\)/)
+  if (!match) {
+    throw new Error(`Invalid HSB color: ${hsb}`)
+  }
+
+  return {
+    space: 'hsb',
+    h: parseFloat(match[1]),
+    s: parseFloat(match[2]),
+    b: parseFloat(match[3]),
+    alpha: match[4] ? parseFloat(match[4]) : 1,
+  }
+}
+
+/**
+ * Normalizes a value to a Color object.
+ * If already a Color, returns it. If a string, parses it.
+ */
+export function normalizeColor(value: string | Color): Color {
+  if (typeof value === 'string') {
+    return parseColor(value)
+  }
+  return value
+}
+
+/**
+ * Checks if a string is a valid color.
+ */
+export function isValidColor(value: string): boolean {
+  try {
+    parseColor(value)
+    return true
+  }
+  catch {
+    return false
+  }
+}

package/src/shared/color/types.ts

@@ -0,0 +1,40 @@
+export type ColorSpace = 'rgb' | 'hsl' | 'hsb'
+
+export interface RGBColor {
+  space: 'rgb'
+  r: number
+  g: number
+  b: number
+  alpha: number
+}
+
+export interface HSLColor {
+  space: 'hsl'
+  h: number
+  s: number
+  l: number
+  alpha: number
+}
+
+export interface HSBColor {
+  space: 'hsb'
+  h: number
+  s: number
+  b: number
+  alpha: number
+}
+
+export type Color = RGBColor | HSLColor | HSBColor
+
+export type RGBChannel = 'red' | 'green' | 'blue' | 'alpha'
+export type HSLChannel = 'hue' | 'saturation' | 'lightness' | 'alpha'
+export type HSBChannel = 'hue' | 'saturation' | 'brightness' | 'alpha'
+export type ColorChannel = RGBChannel | HSLChannel | HSBChannel
+
+export interface ChannelRange {
+  min: number
+  max: number
+  step: number
+}
+
+export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsb'

package/src/shared/color/utils.ts

@@ -0,0 +1,143 @@
+/**
+ * Converts a hex color string to RGB (Red, Green, Blue).
+ * @param hex Hex color string (e.g., "#ff5733" or "#f53")
+ * @returns An object containing red, green, and blue values (0-255).
+ */
+export function hexToRGB(hex: string): { r: number, g: number, b: number } {
+  hex = hex.replace(/^#/, '')
+
+  // Validate hex format (3 or 6 hex digits)
+  if (!/^[0-9A-F]{6}$/i.test(hex) && !/^[0-9A-F]{3}$/i.test(hex)) {
+    throw new Error(`Invalid hex color: ${hex}. Expected format: #RGB or #RRGGBB`)
+  }
+
+  // Handle shorthand hex (e.g., "#FFF" -> "#FFFFFF")
+  if (hex.length === 3) {
+    hex = hex.split('').map(c => c + c).join('')
+  }
+
+  const bigint = parseInt(hex, 16)
+  const r = (bigint >> 16) & 255
+  const g = (bigint >> 8) & 255
+  const b = bigint & 255
+  return { r, g, b }
+}
+
+/**
+ * Converts a hex color string to HSL (Hue, Saturation, Lightness).
+ * @param hex Hex color string (e.g., "#ff5733")
+ * @returns An object containing hue (0-360), saturation (0-100), and lightness (0-100) values.
+ */
+export function hexToHSL(hex: string): { h: number, s: number, l: number } {
+  let { r, g, b } = hexToRGB(hex)
+
+  r /= 255
+  g /= 255
+  b /= 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  let h: number
+  let s: number
+  let l: number = (max + min) / 2
+
+  if (max === min) {
+    h = s = 0 // achromatic
+    l *= 100 // Scale l to 0-100 for consistency with chromatic case
+  }
+  else {
+    const d = max - min
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+    if (max === r) {
+      h = (g - b) / d + (g < b ? 6 : 0)
+    }
+    else if (max === g) {
+      h = (b - r) / d + 2
+    }
+    else {
+      h = (r - g) / d + 4
+    }
+    h /= 6
+    h *= 360
+    s *= 100
+    l *= 100
+  }
+
+  return { h, s, l }
+}
+
+/**
+ * Converts a hex color string to a human-readable color name.
+ * @param hex Hex color string (e.g., "#ff5733")
+ * @returns A human-readable color name based on the hue, saturation, and lightness.
+ */
+export function getColorName(hex: string) {
+  const { h, s, l } = hexToHSL(hex)
+
+  // Handle achromatic colors (low saturation)
+  // Using 0-100 scale for all comparisons
+  if (s < 10) {
+    if (l < 10)
+      return 'black'
+    if (l > 95)
+      return 'white'
+    if (l < 20)
+      return 'very dark gray'
+    if (l < 35)
+      return 'dark gray'
+    if (l < 65)
+      return 'gray'
+    if (l < 80)
+      return 'light gray'
+    return 'very light gray'
+  }
+
+  // Determine base color by hue
+  let baseName
+  if (h < 15 || h >= 345)
+    baseName = 'red'
+  else if (h < 45)
+    baseName = 'orange'
+  else if (h < 75)
+    baseName = 'yellow'
+  else if (h < 105)
+    baseName = 'yellow-green'
+  else if (h < 135)
+    baseName = 'green'
+  else if (h < 165)
+    baseName = 'green-cyan'
+  else if (h < 195)
+    baseName = 'cyan'
+  else if (h < 225)
+    baseName = 'blue'
+  else if (h < 255)
+    baseName = 'blue-violet'
+  else if (h < 285)
+    baseName = 'violet'
+  else if (h < 315)
+    baseName = 'magenta'
+  else baseName = 'red-magenta'
+
+  // Add descriptors based on saturation and lightness
+  // Using 0-100 scale for all comparisons
+  const descriptors = []
+  if (s > 80)
+    descriptors.push('vibrant')
+  else if (s < 30)
+    descriptors.push('muted')
+
+  if (l > 80)
+    descriptors.push('light')
+  else if (l < 30)
+    descriptors.push('dark')
+
+  return descriptors.length > 0
+    ? `${descriptors.join(' ')} ${baseName}`
+    : baseName
+}
+
+export function getColorContrast(hex: string): 'light' | 'dark' {
+  const { r, g, b } = hexToRGB(hex)
+  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
+  return luminance > 0.5 ? 'dark' : 'light'
+}