@zag-js/color-utils 0.9.2 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/color-utils",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Color utilities for zag.js",
   "keywords": [
     "js",
@@ -14,7 +14,8 @@
   "repository": "https://github.com/chakra-ui/zag/tree/main/packages/utilities/color-utils",
   "sideEffects": false,
   "files": [
-    "dist/**/*"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"

package/src/color.ts

@@ -0,0 +1,44 @@
+import type { ColorType, ColorFormat, ColorChannel, ColorChannelRange, ColorAxes } from "./types"
+
+export abstract class Color implements ColorType {
+  abstract toFormat(format: ColorFormat): ColorType
+  abstract toString(format: ColorFormat | "css"): string
+  abstract clone(): ColorType
+  abstract getChannelRange(channel: ColorChannel): ColorChannelRange
+  abstract getColorSpace(): ColorFormat
+  abstract getColorChannels(): [ColorChannel, ColorChannel, ColorChannel]
+
+  toHexInt(): number {
+    return this.toFormat("rgb").toHexInt()
+  }
+
+  getChannelValue(channel: ColorChannel): number {
+    if (channel in this) {
+      return this[channel]
+    }
+
+    throw new Error("Unsupported color channel: " + channel)
+  }
+
+  withChannelValue(channel: ColorChannel, value: number): ColorType {
+    if (channel in this) {
+      let clone = this.clone()
+      clone[channel] = value
+      return clone
+    }
+
+    throw new Error("Unsupported color channel: " + channel)
+  }
+
+  getColorSpaceAxes(xyChannels: { xChannel?: ColorChannel; yChannel?: ColorChannel }): ColorAxes {
+    let { xChannel, yChannel } = xyChannels
+    let xCh = xChannel || this.getColorChannels().find((c) => c !== yChannel)
+    let yCh = yChannel || this.getColorChannels().find((c) => c !== xCh)
+    let zCh = this.getColorChannels().find((c) => c !== xCh && c !== yCh)
+    return { xChannel: xCh!, yChannel: yCh!, zChannel: zCh! }
+  }
+
+  isEqual(color: ColorType): boolean {
+    return this.toHexInt() === color.toHexInt()
+  }
+}

package/src/hsb-color.ts

@@ -0,0 +1,120 @@
+import { Color } from "./color"
+import { HSLColor } from "./hsl-color"
+import { RGBColor } from "./rgb-color"
+import { ColorChannel, ColorChannelRange, ColorFormat, ColorType } from "./types"
+import { clampValue, mod, toFixedNumber } from "./utils"
+
+const HSB_REGEX =
+  /hsb\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%)\)|hsba\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d(.\d+)?)\)/
+
+export class HSBColor extends Color {
+  constructor(private hue: number, private saturation: number, private brightness: number, private alpha: number) {
+    super()
+  }
+
+  static parse(value: string): HSBColor | void {
+    let m: RegExpMatchArray | null
+    if ((m = value.match(HSB_REGEX))) {
+      const [h, s, b, a] = (m[1] ?? m[2]).split(",").map((n) => Number(n.trim().replace("%", "")))
+      return new HSBColor(mod(h, 360), clampValue(s, 0, 100), clampValue(b, 0, 100), clampValue(a ?? 1, 0, 1))
+    }
+  }
+
+  toString(format: ColorFormat | "css") {
+    switch (format) {
+      case "css":
+        return this.toHSL().toString("css")
+      case "hex":
+        return this.toRGB().toString("hex")
+      case "hexa":
+        return this.toRGB().toString("hexa")
+      case "hsb":
+        return `hsb(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.brightness, 2)}%)`
+      case "hsba":
+        return `hsba(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.brightness, 2)}%, ${
+          this.alpha
+        })`
+      default:
+        return this.toFormat(format).toString(format)
+    }
+  }
+
+  toFormat(format: ColorFormat): ColorType {
+    switch (format) {
+      case "hsb":
+      case "hsba":
+        return this
+      case "hsl":
+      case "hsla":
+        return this.toHSL()
+      case "rgb":
+      case "rgba":
+        return this.toRGB()
+      default:
+        throw new Error("Unsupported color conversion: hsb -> " + format)
+    }
+  }
+
+  /**
+   * Converts a HSB color to HSL.
+   * Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_HSL.
+   * @returns An HSLColor object.
+   */
+  private toHSL(): ColorType {
+    let saturation = this.saturation / 100
+    let brightness = this.brightness / 100
+    let lightness = brightness * (1 - saturation / 2)
+    saturation = lightness === 0 || lightness === 1 ? 0 : (brightness - lightness) / Math.min(lightness, 1 - lightness)
+
+    return new HSLColor(
+      toFixedNumber(this.hue, 2),
+      toFixedNumber(saturation * 100, 2),
+      toFixedNumber(lightness * 100, 2),
+      this.alpha,
+    )
+  }
+
+  /**
+   * Converts a HSV color value to RGB.
+   * Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB_alternative.
+   * @returns An RGBColor object.
+   */
+  private toRGB(): ColorType {
+    let hue = this.hue
+    let saturation = this.saturation / 100
+    let brightness = this.brightness / 100
+
+    let fn = (n: number, k = (n + hue / 60) % 6) =>
+      brightness - saturation * brightness * Math.max(Math.min(k, 4 - k, 1), 0)
+
+    return new RGBColor(Math.round(fn(5) * 255), Math.round(fn(3) * 255), Math.round(fn(1) * 255), this.alpha)
+  }
+
+  clone(): ColorType {
+    return new HSBColor(this.hue, this.saturation, this.brightness, this.alpha)
+  }
+
+  getChannelRange(channel: ColorChannel): ColorChannelRange {
+    switch (channel) {
+      case "hue":
+        return { minValue: 0, maxValue: 360, step: 1, pageSize: 15 }
+      case "saturation":
+      case "brightness":
+        return { minValue: 0, maxValue: 100, step: 1, pageSize: 10 }
+      case "alpha":
+        return { minValue: 0, maxValue: 1, step: 0.01, pageSize: 0.1 }
+      default:
+        throw new Error("Unknown color channel: " + channel)
+    }
+  }
+
+  getColorSpace(): ColorFormat {
+    return "hsb"
+  }
+
+  private static colorChannels: [ColorChannel, ColorChannel, ColorChannel] = ["hue", "saturation", "brightness"]
+
+  getColorChannels(): [ColorChannel, ColorChannel, ColorChannel] {
+    return HSBColor.colorChannels
+  }
+}

package/src/hsl-color.ts

@@ -0,0 +1,115 @@
+import { Color } from "./color"
+import { HSBColor } from "./hsb-color"
+import { RGBColor } from "./rgb-color"
+import { ColorChannel, ColorChannelRange, ColorFormat, ColorType } from "./types"
+import { clampValue, mod, toFixedNumber } from "./utils"
+
+export const HSL_REGEX =
+  /hsl\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%)\)|hsla\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d(.\d+)?)\)/
+
+export class HSLColor extends Color {
+  constructor(private hue: number, private saturation: number, private lightness: number, private alpha: number) {
+    super()
+  }
+
+  static parse(value: string): HSLColor | void {
+    let m: RegExpMatchArray | null
+    if ((m = value.match(HSL_REGEX))) {
+      const [h, s, l, a] = (m[1] ?? m[2]).split(",").map((n) => Number(n.trim().replace("%", "")))
+      return new HSLColor(mod(h, 360), clampValue(s, 0, 100), clampValue(l, 0, 100), clampValue(a ?? 1, 0, 1))
+    }
+  }
+
+  toString(format: ColorFormat | "css") {
+    switch (format) {
+      case "hex":
+        return this.toRGB().toString("hex")
+      case "hexa":
+        return this.toRGB().toString("hexa")
+      case "hsl":
+        return `hsl(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.lightness, 2)}%)`
+      case "css":
+      case "hsla":
+        return `hsla(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.lightness, 2)}%, ${
+          this.alpha
+        })`
+      default:
+        return this.toFormat(format).toString(format)
+    }
+  }
+  toFormat(format: ColorFormat): ColorType {
+    switch (format) {
+      case "hsl":
+      case "hsla":
+        return this
+      case "hsb":
+      case "hsba":
+        return this.toHSB()
+      case "rgb":
+      case "rgba":
+        return this.toRGB()
+      default:
+        throw new Error("Unsupported color conversion: hsl -> " + format)
+    }
+  }
+
+  /**
+   * Converts a HSL color to HSB.
+   * Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_HSV.
+   * @returns An HSBColor object.
+   */
+  private toHSB(): ColorType {
+    let saturation = this.saturation / 100
+    let lightness = this.lightness / 100
+    let brightness = lightness + saturation * Math.min(lightness, 1 - lightness)
+    saturation = brightness === 0 ? 0 : 2 * (1 - lightness / brightness)
+    return new HSBColor(
+      toFixedNumber(this.hue, 2),
+      toFixedNumber(saturation * 100, 2),
+      toFixedNumber(brightness * 100, 2),
+      this.alpha,
+    )
+  }
+
+  /**
+   * Converts a HSL color to RGB.
+   * Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_RGB_alternative.
+   * @returns An RGBColor object.
+   */
+  private toRGB(): ColorType {
+    let hue = this.hue
+    let saturation = this.saturation / 100
+    let lightness = this.lightness / 100
+    let a = saturation * Math.min(lightness, 1 - lightness)
+    let fn = (n: number, k = (n + hue / 30) % 12) => lightness - a * Math.max(Math.min(k - 3, 9 - k, 1), -1)
+    return new RGBColor(Math.round(fn(0) * 255), Math.round(fn(8) * 255), Math.round(fn(4) * 255), this.alpha)
+  }
+
+  clone(): ColorType {
+    return new HSLColor(this.hue, this.saturation, this.lightness, this.alpha)
+  }
+
+  getChannelRange(channel: ColorChannel): ColorChannelRange {
+    switch (channel) {
+      case "hue":
+        return { minValue: 0, maxValue: 360, step: 1, pageSize: 15 }
+      case "saturation":
+      case "lightness":
+        return { minValue: 0, maxValue: 100, step: 1, pageSize: 10 }
+      case "alpha":
+        return { minValue: 0, maxValue: 1, step: 0.01, pageSize: 0.1 }
+      default:
+        throw new Error("Unknown color channel: " + channel)
+    }
+  }
+
+  getColorSpace(): ColorFormat {
+    return "hsl"
+  }
+
+  private static colorChannels: [ColorChannel, ColorChannel, ColorChannel] = ["hue", "saturation", "lightness"]
+
+  getColorChannels(): [ColorChannel, ColorChannel, ColorChannel] {
+    return HSLColor.colorChannels
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { Color } from "./color"
+export { parseColor, normalizeColor } from "./parse-color"
+export type { ColorChannel, ColorFormat, ColorAxes } from "./types"

package/src/parse-color.ts

@@ -0,0 +1,20 @@
+import { HSBColor } from "./hsb-color"
+import { HSLColor } from "./hsl-color"
+import { RGBColor } from "./rgb-color"
+import { ColorType } from "./types"
+
+export function parseColor(value: string): ColorType {
+  let result = RGBColor.parse(value) || HSBColor.parse(value) || HSLColor.parse(value)
+  if (!result) {
+    throw new Error("Invalid color value: " + value)
+  }
+  return result
+}
+
+export function normalizeColor(v: string | ColorType) {
+  if (typeof v === "string") {
+    return parseColor(v)
+  } else {
+    return v
+  }
+}

package/src/rgb-color.ts

@@ -0,0 +1,203 @@
+import { Color } from "./color"
+import { HSBColor } from "./hsb-color"
+import { HSLColor } from "./hsl-color"
+import { ColorChannel, ColorChannelRange, ColorFormat, ColorType } from "./types"
+import { clampValue, toFixedNumber } from "./utils"
+
+export class RGBColor extends Color {
+  constructor(private red: number, private green: number, private blue: number, private alpha: number) {
+    super()
+  }
+
+  static parse(value: string) {
+    let colors: (number | undefined)[] = []
+
+    // matching #rgb, #rgba, #rrggbb, #rrggbbaa
+    if (/^#[\da-f]+$/i.test(value) && [4, 5, 7, 9].includes(value.length)) {
+      const values = (value.length < 6 ? value.replace(/[^#]/gi, "$&$&") : value).slice(1).split("")
+      while (values.length > 0) {
+        colors.push(parseInt(values.splice(0, 2).join(""), 16))
+      }
+      colors[3] = colors[3] !== undefined ? colors[3] / 255 : undefined
+    }
+
+    // matching rgb(rrr, ggg, bbb), rgba(rrr, ggg, bbb, 0.a)
+    const match = value.match(/^rgba?\((.*)\)$/)
+
+    if (match?.[1]) {
+      colors = match[1]
+        .split(",")
+        .map((value) => Number(value.trim()))
+        .map((num, i) => clampValue(num, 0, i < 3 ? 255 : 1))
+    }
+
+    //@ts-expect-error
+    return colors.length < 3 ? undefined : new RGBColor(colors[0], colors[1], colors[2], colors[3] ?? 1)
+  }
+
+  toString(format: ColorFormat | "css") {
+    switch (format) {
+      case "hex":
+        return (
+          "#" +
+          (
+            this.red.toString(16).padStart(2, "0") +
+            this.green.toString(16).padStart(2, "0") +
+            this.blue.toString(16).padStart(2, "0")
+          ).toUpperCase()
+        )
+      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")
+          ).toUpperCase()
+        )
+      case "rgb":
+        return `rgb(${this.red}, ${this.green}, ${this.blue})`
+      case "css":
+      case "rgba":
+        return `rgba(${this.red}, ${this.green}, ${this.blue}, ${this.alpha})`
+      default:
+        return this.toFormat(format).toString(format)
+    }
+  }
+
+  toFormat(format: ColorFormat): ColorType {
+    switch (format) {
+      case "hex":
+      case "hexa":
+      case "rgb":
+      case "rgba":
+        return this
+      case "hsb":
+      case "hsba":
+        return this.toHSB()
+      case "hsl":
+      case "hsla":
+        return this.toHSL()
+      default:
+        throw new Error("Unsupported color conversion: rgb -> " + format)
+    }
+  }
+
+  toHexInt(): number {
+    return (this.red << 16) | (this.green << 8) | this.blue
+  }
+
+  /**
+   * Converts an RGB color value to HSB.
+   * Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#From_RGB.
+   * @returns An HSBColor object.
+   */
+  private toHSB(): ColorType {
+    const red = this.red / 255
+    const green = this.green / 255
+    const blue = this.blue / 255
+    const min = Math.min(red, green, blue)
+    const brightness = Math.max(red, green, blue)
+    const chroma = brightness - min
+    const saturation = brightness === 0 ? 0 : chroma / brightness
+    let hue = 0 // achromatic
+
+    if (chroma !== 0) {
+      switch (brightness) {
+        case red:
+          hue = (green - blue) / chroma + (green < blue ? 6 : 0)
+          break
+        case green:
+          hue = (blue - red) / chroma + 2
+          break
+        case blue:
+          hue = (red - green) / chroma + 4
+          break
+      }
+
+      hue /= 6
+    }
+
+    return new HSBColor(
+      toFixedNumber(hue * 360, 2),
+      toFixedNumber(saturation * 100, 2),
+      toFixedNumber(brightness * 100, 2),
+      this.alpha,
+    )
+  }
+
+  /**
+   * Converts an RGB color value to HSL.
+   * Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#From_RGB.
+   * @returns An HSLColor object.
+   */
+  private toHSL(): ColorType {
+    const red = this.red / 255
+    const green = this.green / 255
+    const blue = this.blue / 255
+    const min = Math.min(red, green, blue)
+    const max = Math.max(red, green, blue)
+    const lightness = (max + min) / 2
+    const chroma = max - min
+
+    let hue = -1
+    let saturation = -1
+
+    if (chroma === 0) {
+      hue = saturation = 0 // achromatic
+    } else {
+      saturation = chroma / (lightness < 0.5 ? max + min : 2 - max - min)
+
+      switch (max) {
+        case red:
+          hue = (green - blue) / chroma + (green < blue ? 6 : 0)
+          break
+        case green:
+          hue = (blue - red) / chroma + 2
+          break
+        case blue:
+          hue = (red - green) / chroma + 4
+          break
+      }
+
+      hue /= 6
+    }
+
+    return new HSLColor(
+      toFixedNumber(hue * 360, 2),
+      toFixedNumber(saturation * 100, 2),
+      toFixedNumber(lightness * 100, 2),
+      this.alpha,
+    )
+  }
+
+  clone(): ColorType {
+    return new RGBColor(this.red, this.green, this.blue, this.alpha)
+  }
+
+  getChannelRange(channel: ColorChannel): ColorChannelRange {
+    switch (channel) {
+      case "red":
+      case "green":
+      case "blue":
+        return { minValue: 0x0, maxValue: 0xff, step: 0x1, pageSize: 0x11 }
+      case "alpha":
+        return { minValue: 0, maxValue: 1, step: 0.01, pageSize: 0.1 }
+      default:
+        throw new Error("Unknown color channel: " + channel)
+    }
+  }
+
+  getColorSpace(): ColorFormat {
+    return "rgb"
+  }
+
+  private static colorChannels: [ColorChannel, ColorChannel, ColorChannel] = ["red", "green", "blue"]
+
+  getColorChannels(): [ColorChannel, ColorChannel, ColorChannel] {
+    return RGBColor.colorChannels
+  }
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+export type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba"
+
+export type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha"
+
+export type ColorAxes = { xChannel: ColorChannel; yChannel: ColorChannel; zChannel: ColorChannel }
+
+export interface ColorChannelRange {
+  /** The minimum value of the color channel. */
+  minValue: number
+  /** The maximum value of the color channel. */
+  maxValue: number
+  /** The step value of the color channel, used when incrementing and decrementing. */
+  step: number
+  /** The page step value of the color channel, used when incrementing and decrementing. */
+  pageSize: number
+}
+
+export interface ColorType {
+  /** Converts the color to the given color format, and returns a new Color object. */
+  toFormat(format: ColorFormat): ColorType
+  /** Converts the color to a string in the given format. */
+  toString(format: ColorFormat | "css"): string
+  /** Converts the color to hex, and returns an integer representation. */
+  toHexInt(): number
+  /**
+   * Returns the numeric value for a given channel.
+   * Throws an error if the channel is unsupported in the current color format.
+   */
+  getChannelValue(channel: ColorChannel): number
+  /**
+   * Sets the numeric value for a given channel, and returns a new Color object.
+   * Throws an error if the channel is unsupported in the current color format.
+   */
+  withChannelValue(channel: ColorChannel, value: number): ColorType
+  /**
+   * Returns the minimum, maximum, and step values for a given channel.
+   */
+  getChannelRange(channel: ColorChannel): ColorChannelRange
+  /**
+   * Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color.
+   */
+  getColorSpace(): ColorFormat
+  /**
+   * Returns the color space axes, xChannel, yChannel, zChannel.
+   */
+  getColorSpaceAxes(xyChannels: { xChannel?: ColorChannel; yChannel?: ColorChannel }): ColorAxes
+  /**
+   * Returns an array of the color channels within the current color space space.
+   */
+  getColorChannels(): [ColorChannel, ColorChannel, ColorChannel]
+  /**
+   * Returns a new Color object with the same values as the current color.
+   */
+  clone(): ColorType
+  /**
+   * Whether the color is equal to another color.
+   */
+  isEqual(color: ColorType): boolean
+}

package/src/utils.ts

@@ -0,0 +1,11 @@
+export function mod(n: number, m: number) {
+  return ((n % m) + m) % m
+}
+
+export function toFixedNumber(num: number, digits: number) {
+  return Math.round(Math.pow(10, digits) * num) / Math.pow(10, digits)
+}
+
+export function clampValue(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max)
+}