@zag-js/color-utils 0.23.0 → 0.25.0

package/dist/index.d.mts

@@ -1,10 +1,12 @@
 type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba";
 type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
-type ColorAxes = {
+interface Color2DAxes {
     xChannel: ColorChannel;
     yChannel: ColorChannel;
+}
+interface ColorAxes extends Color2DAxes {
     zChannel: ColorChannel;
-};
+}
 interface ColorChannelRange {
     /** The minimum value of the color channel. */
     minValue: number;
@@ -18,10 +20,14 @@ interface ColorChannelRange {
 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 JSON object. */
+    toJSON(): Record<string, number>;
     /** 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;
+    /** The output format of the color. */
+    outputFormat: ColorFormat | undefined;
     /**
      * Returns the numeric value for a given channel.
      * Throws an error if the channel is unsupported in the current color format.
@@ -39,18 +45,15 @@ interface ColorType {
     /**
      * Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color.
      */
-    getColorFormat(): ColorFormat;
+    getFormat(): ColorFormat;
     /**
      * Returns the color space axes, xChannel, yChannel, zChannel.
      */
-    getColorSpaceAxes(xyChannels: {
-        xChannel?: ColorChannel;
-        yChannel?: ColorChannel;
-    }): ColorAxes;
+    getColorAxes(xyChannels: Color2DAxes): ColorAxes;
     /**
      * Returns an array of the color channels within the current color space space.
      */
-    getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
+    getChannels(): [ColorChannel, ColorChannel, ColorChannel];
     /**
      * Returns a new Color object with the same values as the current color.
      */
@@ -59,23 +62,41 @@ interface ColorType {
      * Whether the color is equal to another color.
      */
     isEqual(color: ColorType): boolean;
+    /**
+     * Increments the color channel by the given step size, and returns a new Color object.
+     */
+    incrementChannel(channel: ColorChannel, stepSize: number): ColorType;
+    /**
+     * Decrements the color channel by the given step size, and returns a new Color object.
+     */
+    decrementChannel(channel: ColorChannel, stepSize: number): ColorType;
+    /**
+     * Returns the color channel value as a percentage of the channel range.
+     */
+    getChannelValuePercent(channel: ColorChannel, value?: number): number;
+    /**
+     * Returns the color channel value for a given percentage of the channel range.
+     */
+    getChannelPercentValue(channel: ColorChannel, percent: number): number;
 }
 
 declare abstract class Color implements ColorType {
     abstract toFormat(format: ColorFormat): ColorType;
+    abstract toJSON(): Record<string, number>;
     abstract toString(format: ColorFormat | "css"): string;
     abstract clone(): ColorType;
     abstract getChannelRange(channel: ColorChannel): ColorChannelRange;
-    abstract getColorFormat(): ColorFormat;
-    abstract getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
-    hasColorChannel(channel: ColorChannel): boolean;
+    abstract getFormat(): ColorFormat;
+    abstract getChannels(): [ColorChannel, ColorChannel, ColorChannel];
+    outputFormat: ColorFormat | undefined;
     toHexInt(): number;
     getChannelValue(channel: ColorChannel): number;
+    getChannelValuePercent(channel: ColorChannel, valueToCheck?: number): number;
+    getChannelPercentValue(channel: ColorChannel, percentToCheck: number): number;
     withChannelValue(channel: ColorChannel, value: number): ColorType;
-    getColorSpaceAxes(xyChannels: {
-        xChannel?: ColorChannel;
-        yChannel?: ColorChannel;
-    }): ColorAxes;
+    getColorAxes(xyChannels: Color2DAxes): ColorAxes;
+    incrementChannel(channel: ColorChannel, stepSize: number): ColorType;
+    decrementChannel(channel: ColorChannel, stepSize: number): ColorType;
     isEqual(color: ColorType): boolean;
 }
 

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba";
 type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
-type ColorAxes = {
+interface Color2DAxes {
     xChannel: ColorChannel;
     yChannel: ColorChannel;
+}
+interface ColorAxes extends Color2DAxes {
     zChannel: ColorChannel;
-};
+}
 interface ColorChannelRange {
     /** The minimum value of the color channel. */
     minValue: number;
@@ -18,10 +20,14 @@ interface ColorChannelRange {
 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 JSON object. */
+    toJSON(): Record<string, number>;
     /** 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;
+    /** The output format of the color. */
+    outputFormat: ColorFormat | undefined;
     /**
      * Returns the numeric value for a given channel.
      * Throws an error if the channel is unsupported in the current color format.
@@ -39,18 +45,15 @@ interface ColorType {
     /**
      * Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color.
      */
-    getColorFormat(): ColorFormat;
+    getFormat(): ColorFormat;
     /**
      * Returns the color space axes, xChannel, yChannel, zChannel.
      */
-    getColorSpaceAxes(xyChannels: {
-        xChannel?: ColorChannel;
-        yChannel?: ColorChannel;
-    }): ColorAxes;
+    getColorAxes(xyChannels: Color2DAxes): ColorAxes;
     /**
      * Returns an array of the color channels within the current color space space.
      */
-    getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
+    getChannels(): [ColorChannel, ColorChannel, ColorChannel];
     /**
      * Returns a new Color object with the same values as the current color.
      */
@@ -59,23 +62,41 @@ interface ColorType {
      * Whether the color is equal to another color.
      */
     isEqual(color: ColorType): boolean;
+    /**
+     * Increments the color channel by the given step size, and returns a new Color object.
+     */
+    incrementChannel(channel: ColorChannel, stepSize: number): ColorType;
+    /**
+     * Decrements the color channel by the given step size, and returns a new Color object.
+     */
+    decrementChannel(channel: ColorChannel, stepSize: number): ColorType;
+    /**
+     * Returns the color channel value as a percentage of the channel range.
+     */
+    getChannelValuePercent(channel: ColorChannel, value?: number): number;
+    /**
+     * Returns the color channel value for a given percentage of the channel range.
+     */
+    getChannelPercentValue(channel: ColorChannel, percent: number): number;
 }
 
 declare abstract class Color implements ColorType {
     abstract toFormat(format: ColorFormat): ColorType;
+    abstract toJSON(): Record<string, number>;
     abstract toString(format: ColorFormat | "css"): string;
     abstract clone(): ColorType;
     abstract getChannelRange(channel: ColorChannel): ColorChannelRange;
-    abstract getColorFormat(): ColorFormat;
-    abstract getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
-    hasColorChannel(channel: ColorChannel): boolean;
+    abstract getFormat(): ColorFormat;
+    abstract getChannels(): [ColorChannel, ColorChannel, ColorChannel];
+    outputFormat: ColorFormat | undefined;
     toHexInt(): number;
     getChannelValue(channel: ColorChannel): number;
+    getChannelValuePercent(channel: ColorChannel, valueToCheck?: number): number;
+    getChannelPercentValue(channel: ColorChannel, percentToCheck: number): number;
     withChannelValue(channel: ColorChannel, value: number): ColorType;
-    getColorSpaceAxes(xyChannels: {
-        xChannel?: ColorChannel;
-        yChannel?: ColorChannel;
-    }): ColorAxes;
+    getColorAxes(xyChannels: Color2DAxes): ColorAxes;
+    incrementChannel(channel: ColorChannel, stepSize: number): ColorType;
+    decrementChannel(channel: ColorChannel, stepSize: number): ColorType;
     isEqual(color: ColorType): boolean;
 }
 

package/dist/index.js

@@ -16,7 +16,7 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toCommonJS = (mod2) => __copyProps(__defProp({}, "__esModule", { value: true }), mod2);
+var __toCommonJS = (mod3) => __copyProps(__defProp({}, "__esModule", { value: true }), mod3);
 var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
@@ -156,14 +156,14 @@ var generateHSB_B = (orientation, dir, alphaValue) => {
 // src/area-gradient.ts
 function getColorAreaGradient(color, options) {
   const { xChannel, yChannel, dir: dirProp } = options;
-  const { zChannel } = color.getColorSpaceAxes({ xChannel, yChannel });
+  const { zChannel } = color.getColorAxes({ xChannel, yChannel });
   const zValue = color.getChannelValue(zChannel);
   const { minValue: zMin, maxValue: zMax } = color.getChannelRange(zChannel);
   const orientation = ["top", dirProp === "rtl" ? "left" : "right"];
   let dir = false;
   let background = { areaStyles: {}, areaGradientStyles: {} };
   let alphaValue = (zValue - zMin) / (zMax - zMin);
-  let isHSL = color.getColorFormat() === "hsl";
+  let isHSL = color.getFormat() === "hsl";
   switch (zChannel) {
     case "red": {
       dir = xChannel === "green";
@@ -213,19 +213,37 @@ function getColorAreaGradient(color, options) {
 }
 
 // src/color.ts
+var import_numeric_range = require("@zag-js/numeric-range");
+var isEqualObject = (a, b) => {
+  if (Object.keys(a).length !== Object.keys(b).length)
+    return false;
+  for (let key in a)
+    if (a[key] !== b[key])
+      return false;
+  return true;
+};
 var Color = class {
-  hasColorChannel(channel) {
-    return this.getColorChannels().includes(channel);
+  constructor() {
+    __publicField(this, "outputFormat");
   }
   toHexInt() {
     return this.toFormat("rgb").toHexInt();
   }
   getChannelValue(channel) {
-    if (channel in this) {
+    if (channel in this)
       return this[channel];
-    }
     throw new Error("Unsupported color channel: " + channel);
   }
+  getChannelValuePercent(channel, valueToCheck) {
+    const value = valueToCheck ?? this.getChannelValue(channel);
+    const { minValue, maxValue } = this.getChannelRange(channel);
+    return (0, import_numeric_range.getValuePercent)(value, minValue, maxValue);
+  }
+  getChannelPercentValue(channel, percentToCheck) {
+    const { minValue, maxValue, step } = this.getChannelRange(channel);
+    const percentValue = (0, import_numeric_range.getPercentValue)(percentToCheck, minValue, maxValue, step);
+    return (0, import_numeric_range.snapValueToStep)(percentValue, minValue, maxValue, step);
+  }
   withChannelValue(channel, value) {
     if (channel in this) {
       let clone = this.clone();
@@ -234,30 +252,40 @@ var Color = class {
     }
     throw new Error("Unsupported color channel: " + channel);
   }
-  getColorSpaceAxes(xyChannels) {
+  getColorAxes(xyChannels) {
     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);
+    let xCh = xChannel || this.getChannels().find((c) => c !== yChannel);
+    let yCh = yChannel || this.getChannels().find((c) => c !== xCh);
+    let zCh = this.getChannels().find((c) => c !== xCh && c !== yCh);
     return { xChannel: xCh, yChannel: yCh, zChannel: zCh };
   }
+  incrementChannel(channel, stepSize) {
+    const { minValue, maxValue, step } = this.getChannelRange(channel);
+    const value = (0, import_numeric_range.snapValueToStep)(
+      (0, import_numeric_range.clampValue)(this.getChannelValue(channel) + stepSize, minValue, maxValue),
+      minValue,
+      maxValue,
+      step
+    );
+    return this.withChannelValue(channel, value);
+  }
+  decrementChannel(channel, stepSize) {
+    return this.incrementChannel(channel, -stepSize);
+  }
   isEqual(color) {
-    return this.toHexInt() === color.toHexInt() && this.getChannelValue("alpha") === color.getChannelValue("alpha");
+    const isSame = isEqualObject(this.toJSON(), color.toJSON());
+    return isSame && this.getChannelValue("alpha") === color.getChannelValue("alpha");
   }
 };
 
-// src/utils.ts
-function mod(n, m) {
-  return (n % m + m) % m;
-}
-function toFixedNumber(num, digits) {
-  return Math.round(Math.pow(10, digits) * num) / Math.pow(10, digits);
-}
-function clampValue(value, min, max) {
-  return Math.min(Math.max(value, min), max);
-}
+// src/hsb-color.ts
+var import_numeric_range4 = require("@zag-js/numeric-range");
+
+// src/hsl-color.ts
+var import_numeric_range3 = require("@zag-js/numeric-range");
 
 // src/rgb-color.ts
+var import_numeric_range2 = require("@zag-js/numeric-range");
 var _RGBColor = class _RGBColor extends Color {
   constructor(red, green, blue, alpha) {
     super();
@@ -277,7 +305,7 @@ var _RGBColor = class _RGBColor extends Color {
     }
     const match = value.match(/^rgba?\((.*)\)$/);
     if (match?.[1]) {
-      colors = match[1].split(",").map((value2) => Number(value2.trim())).map((num, i) => clampValue(num, 0, i < 3 ? 255 : 1));
+      colors = match[1].split(",").map((value2) => Number(value2.trim())).map((num, i) => (0, import_numeric_range2.clampValue)(num, 0, i < 3 ? 255 : 1));
     }
     return colors.length < 3 ? void 0 : new _RGBColor(colors[0], colors[1], colors[2], colors[3] ?? 1);
   }
@@ -345,10 +373,10 @@ var _RGBColor = class _RGBColor extends Color {
       hue /= 6;
     }
     return new HSBColor(
-      toFixedNumber(hue * 360, 2),
-      toFixedNumber(saturation * 100, 2),
-      toFixedNumber(brightness * 100, 2),
-      this.alpha
+      (0, import_numeric_range2.toFixedNumber)(hue * 360, 2),
+      (0, import_numeric_range2.toFixedNumber)(saturation * 100, 2),
+      (0, import_numeric_range2.toFixedNumber)(brightness * 100, 2),
+      (0, import_numeric_range2.toFixedNumber)(this.alpha, 2)
     );
   }
   /**
@@ -384,10 +412,10 @@ var _RGBColor = class _RGBColor extends Color {
       hue /= 6;
     }
     return new HSLColor(
-      toFixedNumber(hue * 360, 2),
-      toFixedNumber(saturation * 100, 2),
-      toFixedNumber(lightness * 100, 2),
-      this.alpha
+      (0, import_numeric_range2.toFixedNumber)(hue * 360, 2),
+      (0, import_numeric_range2.toFixedNumber)(saturation * 100, 2),
+      (0, import_numeric_range2.toFixedNumber)(lightness * 100, 2),
+      (0, import_numeric_range2.toFixedNumber)(this.alpha, 2)
     );
   }
   clone() {
@@ -405,10 +433,13 @@ var _RGBColor = class _RGBColor extends Color {
         throw new Error("Unknown color channel: " + channel);
     }
   }
-  getColorFormat() {
+  toJSON() {
+    return { r: this.red, g: this.green, b: this.blue };
+  }
+  getFormat() {
     return "rgb";
   }
-  getColorChannels() {
+  getChannels() {
     return _RGBColor.colorChannels;
   }
 };
@@ -429,7 +460,7 @@ var _HSLColor = class _HSLColor extends Color {
     let m;
     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));
+      return new _HSLColor((0, import_numeric_range3.mod)(h, 360), (0, import_numeric_range3.clampValue)(s, 0, 100), (0, import_numeric_range3.clampValue)(l, 0, 100), (0, import_numeric_range3.clampValue)(a ?? 1, 0, 1));
     }
   }
   toString(format) {
@@ -439,10 +470,10 @@ var _HSLColor = class _HSLColor extends Color {
       case "hexa":
         return this.toRGB().toString("hexa");
       case "hsl":
-        return `hsl(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.lightness, 2)}%)`;
+        return `hsl(${this.hue}, ${(0, import_numeric_range3.toFixedNumber)(this.saturation, 2)}%, ${(0, import_numeric_range3.toFixedNumber)(this.lightness, 2)}%)`;
       case "css":
       case "hsla":
-        return `hsla(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.lightness, 2)}%, ${this.alpha})`;
+        return `hsla(${this.hue}, ${(0, import_numeric_range3.toFixedNumber)(this.saturation, 2)}%, ${(0, import_numeric_range3.toFixedNumber)(this.lightness, 2)}%, ${this.alpha})`;
       default:
         return this.toFormat(format).toString(format);
     }
@@ -473,10 +504,10 @@ var _HSLColor = class _HSLColor extends Color {
     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
+      (0, import_numeric_range3.toFixedNumber)(this.hue, 2),
+      (0, import_numeric_range3.toFixedNumber)(saturation * 100, 2),
+      (0, import_numeric_range3.toFixedNumber)(brightness * 100, 2),
+      (0, import_numeric_range3.toFixedNumber)(this.alpha, 2)
     );
   }
   /**
@@ -490,7 +521,12 @@ var _HSLColor = class _HSLColor extends Color {
     let lightness = this.lightness / 100;
     let a = saturation * Math.min(lightness, 1 - lightness);
     let fn = (n, 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);
+    return new RGBColor(
+      Math.round(fn(0) * 255),
+      Math.round(fn(8) * 255),
+      Math.round(fn(4) * 255),
+      (0, import_numeric_range3.toFixedNumber)(this.alpha, 2)
+    );
   }
   clone() {
     return new _HSLColor(this.hue, this.saturation, this.lightness, this.alpha);
@@ -508,10 +544,13 @@ var _HSLColor = class _HSLColor extends Color {
         throw new Error("Unknown color channel: " + channel);
     }
   }
-  getColorFormat() {
+  toJSON() {
+    return { h: this.hue, s: this.saturation, l: this.lightness };
+  }
+  getFormat() {
     return "hsl";
   }
-  getColorChannels() {
+  getChannels() {
     return _HSLColor.colorChannels;
   }
 };
@@ -532,7 +571,7 @@ var _HSBColor = class _HSBColor extends Color {
     let m;
     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));
+      return new _HSBColor((0, import_numeric_range4.mod)(h, 360), (0, import_numeric_range4.clampValue)(s, 0, 100), (0, import_numeric_range4.clampValue)(b, 0, 100), (0, import_numeric_range4.clampValue)(a ?? 1, 0, 1));
     }
   }
   toString(format) {
@@ -544,9 +583,9 @@ var _HSBColor = class _HSBColor extends Color {
       case "hexa":
         return this.toRGB().toString("hexa");
       case "hsb":
-        return `hsb(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.brightness, 2)}%)`;
+        return `hsb(${this.hue}, ${(0, import_numeric_range4.toFixedNumber)(this.saturation, 2)}%, ${(0, import_numeric_range4.toFixedNumber)(this.brightness, 2)}%)`;
       case "hsba":
-        return `hsba(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.brightness, 2)}%, ${this.alpha})`;
+        return `hsba(${this.hue}, ${(0, import_numeric_range4.toFixedNumber)(this.saturation, 2)}%, ${(0, import_numeric_range4.toFixedNumber)(this.brightness, 2)}%, ${this.alpha})`;
       default:
         return this.toFormat(format).toString(format);
     }
@@ -577,10 +616,10 @@ var _HSBColor = class _HSBColor extends Color {
     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
+      (0, import_numeric_range4.toFixedNumber)(this.hue, 2),
+      (0, import_numeric_range4.toFixedNumber)(saturation * 100, 2),
+      (0, import_numeric_range4.toFixedNumber)(lightness * 100, 2),
+      (0, import_numeric_range4.toFixedNumber)(this.alpha, 2)
     );
   }
   /**
@@ -593,7 +632,12 @@ var _HSBColor = class _HSBColor extends Color {
     let saturation = this.saturation / 100;
     let brightness = this.brightness / 100;
     let fn = (n, 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);
+    return new RGBColor(
+      Math.round(fn(5) * 255),
+      Math.round(fn(3) * 255),
+      Math.round(fn(1) * 255),
+      (0, import_numeric_range4.toFixedNumber)(this.alpha, 2)
+    );
   }
   clone() {
     return new _HSBColor(this.hue, this.saturation, this.brightness, this.alpha);
@@ -611,10 +655,13 @@ var _HSBColor = class _HSBColor extends Color {
         throw new Error("Unknown color channel: " + channel);
     }
   }
-  getColorFormat() {
+  toJSON() {
+    return { h: this.hue, s: this.saturation, b: this.brightness };
+  }
+  getFormat() {
     return "hsb";
   }
-  getColorChannels() {
+  getChannels() {
     return _HSBColor.colorChannels;
   }
 };