@auaust/jaune 0.0.0 → 0.0.1

package/src/classes/Color.ts

@@ -0,0 +1,362 @@
+import { N } from "@auaust/primitive-kit";
+import type { Writable } from "type-fest";
+import type {
+  ColorChannels,
+  ColorValue,
+  MaybeNamedColor,
+  NamedColor,
+  Rgb,
+} from "~";
+import {
+  brightness,
+  closestNamedColor,
+  contrast,
+  distance,
+  fallbackColor,
+  grayscale,
+  isAliasToNamedColor,
+  isBright,
+  isColor,
+  isColorChannels,
+  isDark,
+  isHex,
+  isNamedColor,
+  isOpaque,
+  isRgb,
+  isTranslucent,
+  isTransparent,
+  luminance,
+  namedColorAliases,
+  parseColor,
+  parseHex,
+  parseNamedColor,
+  parseRgb,
+  toAlphaChannel,
+  toColorChannels,
+  toHex,
+  toRgb,
+  toRgbChannel,
+  type,
+} from "~/utils";
+import { cache, channels } from "~/utils/symbols";
+
+export class Color {
+  protected [channels]: Required<Writable<ColorChannels>> = undefined!;
+  protected [cache]: Map<string | Function, any> = new Map();
+
+  constructor(value: ColorChannels) {
+    this[channels] = { ...toColorChannels(value) };
+  }
+
+  static from(value: ColorValue): Color;
+  static from(red: number, green: number, blue: number, alpha?: number): Color;
+  static from(value: ColorValue | number, ...rest: number[]): Color {
+    if (N.is(value)) {
+      return new this({ r: value, g: rest[0], b: rest[1], a: rest[2] });
+    }
+
+    return new this(parseColor(value ?? fallbackColor));
+  }
+
+  static fromChannels(channels: ColorChannels): Color {
+    return new this(channels);
+  }
+
+  static fromRgb(rgb: Rgb): Color {
+    return new this(parseRgb(rgb));
+  }
+
+  static fromHex(hex: string): Color {
+    return new this(parseHex(hex));
+  }
+
+  static fromName(name: MaybeNamedColor): Color {
+    return new this(parseNamedColor(name));
+  }
+
+  /**
+   * Returns the color type of the passed value, or `undefined` if it's not a color.
+   *
+   * It is slightly stricter than the logic used to parse colors.
+   * It would return false for an array of channels which values are not within the expected range, where `parseColor` would return a color with the invalid values clamped.
+   */
+  static type = type;
+
+  /** Returns a boolean indicating whether the passed value is a color. */
+  static isColor = isColor;
+
+  /** @alias Color#isColor */
+  static is = isColor;
+
+  /** Returns a boolean indicating whether the passed value is a HEX color string. */
+  static isHex = isHex;
+
+  /** Returns a boolean indicating whether the passed value is a named color. */
+  static isNamedColor = isNamedColor;
+
+  /** Returns a boolean indicating whether the passed value is a color channel object. */
+  static isColorChannels = isColorChannels;
+
+  /** Returns a boolean indicating whether the passed value is a RGB color tuple. */
+  static isRgb = isRgb;
+
+  /** Returns all the aliases of a named color, including the name itself. */
+  static namedColorAliases = namedColorAliases;
+
+  /** Returns a boolean whether two named colors are aliases, meaning they have the same HEX value. */
+  static isAliasToNamedColor = isAliasToNamedColor;
+
+  /**
+   * Returns a new `Color` instance with the same channels as the current one.
+   * If you want the clone to have different channels, use the `with` method.
+   */
+  clone(): Color {
+    return Color.fromChannels(this[channels]);
+  }
+
+  /** Returns a new `Color` instance with the passed channels overriding the current ones. */
+  with(value: Partial<Pick<ColorChannels, "r" | "g" | "b" | "a">>): Color {
+    return Color.fromChannels({
+      ...this[channels],
+      ...value,
+      isFallback: false,
+      isTransformed: false,
+    });
+  }
+
+  /** Returns a new `Color` instance with the specified red channel. */
+  withRed(value: number): Color {
+    return this.with({ r: value });
+  }
+
+  /** Returns a new `Color` instance with the specified green channel. */
+  withGreen(value: number): Color {
+    return this.with({ g: value });
+  }
+
+  /** Returns a new `Color` instance with the specified blue channel. */
+  withBlue(value: number): Color {
+    return this.with({ b: value });
+  }
+
+  /** Returns a new `Color` instance with the specified alpha channel. */
+  withAlpha(value: number): Color {
+    return this.with({ a: value });
+  }
+
+  private updated(): this {
+    this[cache].clear();
+    this[channels].isFallback = false; // once updated, it's no longer a fallback
+    this[channels].isTransformed = false;
+    return this;
+  }
+
+  set(channel: "r" | "g" | "b" | "a", value: number): this {
+    this[channels][channel] =
+      channel === "a" ? toAlphaChannel(value) : toRgbChannel(value);
+    return this.updated();
+  }
+
+  /** The red channel of the color. */
+  get red(): number {
+    return this[channels].r;
+  }
+
+  /** @see Color#red */
+  get r(): number {
+    return this[channels].r;
+  }
+
+  set red(value: number) {
+    this.setRed(value);
+  }
+
+  setRed(value: number): this {
+    return this.set("r", value);
+  }
+
+  /** The green channel of the color. */
+  get green(): number {
+    return this[channels].g;
+  }
+
+  /** @see Color#green */
+  get g(): number {
+    return this[channels].g;
+  }
+
+  set green(value: number) {
+    this.setGreen(value);
+  }
+
+  setGreen(value: number): this {
+    return this.set("g", value);
+  }
+
+  /** The blue channel of the color. */
+  get blue(): number {
+    return this[channels].b;
+  }
+
+  /** @see Color#blue */
+  get b(): number {
+    return this[channels].b;
+  }
+
+  set blue(value: number) {
+    this.setBlue(value);
+  }
+
+  setBlue(value: number): this {
+    return this.set("b", value);
+  }
+
+  /** The alpha channel of the color. */
+  get alpha(): number {
+    return this[channels].a;
+  }
+
+  /** @see Color#alpha */
+  get a(): number {
+    return this[channels].a;
+  }
+
+  set alpha(value: number) {
+    this.setAlpha(value);
+  }
+
+  setAlpha(value: number): this {
+    return this.set("a", value);
+  }
+
+  /**
+   * Whether the color is the fallback color, which is used when the input is invalid.
+   * As soon as a color channel is updated, this will always be `false`.
+   */
+  get isFallback(): boolean {
+    return this[channels].isFallback;
+  }
+
+  /**
+   * Whether any of the channels have been transformed by the color parser.
+   * As soon as a color channel is updated, this will always be `false`.
+   */
+  get isTransformed(): boolean {
+    return this[channels].isTransformed;
+  }
+
+  /** Helper to cache data until the channels are updated. */
+  private memoize<T>(getter: (channels: ColorChannels) => T, key?: string): T {
+    // If no key is passed, we use the getter function as the key
+    // This means no key is required when the getter is a named function, while allowing to use anonymous functions within getters as well by passing a key
+    const cacheKey = key ?? getter;
+
+    if (!this[cache].has(cacheKey)) {
+      this[cache].set(cacheKey, getter(this[channels]));
+    }
+
+    return this[cache].get(cacheKey);
+  }
+
+  /** Checks if the color is fully opaque. */
+  get isOpaque(): boolean {
+    return this.memoize(isOpaque);
+  }
+
+  /** Checks if the color is fully transparent. */
+  get isTransparent(): boolean {
+    return this.memoize(isTransparent);
+  }
+
+  /** Checks if the color is at least partially transparent. */
+  get isTranslucent(): boolean {
+    return this.memoize(isTranslucent);
+  }
+
+  /**
+   * Returns the closest named color. If aliases exist, which one is returned is not guaranteed.
+   * In some cases, calling `namedColorAliases()` on the result might help achieve the desired result.
+   */
+  get closestNamedColor(): NamedColor {
+    return this.memoize(closestNamedColor);
+  }
+
+  /** The relative brightness of the color. */
+  get brightness(): number {
+    return this.memoize(brightness);
+  }
+
+  /** Whether the color is considered bright. */
+  get isBright(): boolean {
+    return this.memoize(isBright);
+  }
+
+  /** Whether the color is considered dark. */
+  get isDark(): boolean {
+    return this.memoize(isDark);
+  }
+
+  /** Whether the color is brighter than the passed threshold or color. */
+  isBrighterThan(threshold: Color | number): boolean {
+    return (
+      this.brightness >
+      (threshold instanceof Color ? threshold.brightness : threshold)
+    );
+  }
+
+  /** Whether the color is darker than the passed threshold or color. */
+  isDarkerThan(threshold: Color | number): boolean {
+    return (
+      this.brightness <
+      (threshold instanceof Color ? threshold.brightness : threshold)
+    );
+  }
+
+  /** Returns the relative luminance of the color. */
+  get luminance(): number {
+    return this.memoize(luminance);
+  }
+
+  /** Returns the contrast ratio between this color and another. */
+  contrast(color: ColorValue): number {
+    return contrast(this[channels], Color.from(color)[channels]);
+  }
+
+  /** Returns the distance between this color and another. If `alpha` is `true`, the alpha channel is included in the calculation. */
+  distance(color: ColorValue, alpha = false): number {
+    return distance(this[channels], Color.from(color)[channels], alpha);
+  }
+
+  /** Returns a new color with the grayscale equivalent of the current color, preserving the alpha channel. */
+  toGrayscale(): Color {
+    return Color.fromChannels(grayscale(this[channels]));
+  }
+
+  toHex(): string {
+    return this.memoize(toHex);
+  }
+
+  toRgb(): Rgb {
+    return this.memoize(toRgb);
+  }
+
+  toChannels(): ColorChannels {
+    return this.memoize(toColorChannels); // can't return `this[channels]` directly as it's writable, and could cause unexpected behavior
+  }
+
+  toString(): string {
+    return this.toHex();
+  }
+
+  valueOf(): string {
+    return this.toString();
+  }
+
+  [Symbol.toPrimitive](): string {
+    return this.toString();
+  }
+
+  toJSON(): string {
+    return this.toString();
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { Color } from "~/classes/Color";
+export type {
+  ColorChannels,
+  ColorType,
+  ColorValue,
+  Hex,
+  MaybeNamedColor,
+  NamedColor,
+  Rgb,
+} from "~/types";

package/src/types/index.ts

@@ -0,0 +1,84 @@
+import type { Color } from "~/classes/Color";
+import type { namedColorsMap } from "~/utils";
+
+type ColorTypeMap = {
+  channels: ColorChannels;
+  color: Color;
+  hex: Hex;
+  named: NamedColor;
+  rgb: Rgb;
+};
+
+/**
+ * The known color types.
+ *
+ * `channels` - An object of each color channel.
+ * `color` - A `Color` instance.
+ * `hex` - A HEX color string.
+ * `named` - A CSS color name.
+ * `rgb` - A tuple representing RGB color channels.
+ */
+export type ColorType = keyof ColorTypeMap;
+
+/** Represents a color in any of the various supported formats. */
+export type ColorValue = ColorTypeMap[ColorType];
+
+/** A HEX color string. It must start with a hash (#) character followed by 3, 4, 6, or 8 hexadecimal digits. */
+export type Hex = `#${string}` | (string & {});
+
+/**
+ * A tuple representing RGB color channels.
+ *
+ * The first three elements are integers between 0 and 255 representing the red, green, and blue channels, respectively.
+ * The fourth element is a number between 0 and 1 representing the alpha channel.
+ */
+export type Rgb =
+  | readonly [r: number, g: number, b: number, a?: number]
+  | readonly number[]; // The above tuple type alone would make the type too annoying to use
+
+/**
+ * A CSS color name.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+ */
+export type NamedColor = keyof typeof namedColorsMap;
+export type MaybeNamedColor = NamedColor | (string & {});
+
+/**
+ * An object of each color channel.
+ *
+ * `r`, `g`, and `b` are integers between 0 and 255 representing the red, green, and blue channels, respectively.
+ * `a` is a number between 0 and 1 representing the alpha channel.
+ * It may contain metadata about the color and its handling by the color parser.
+ */
+export type ColorChannels = {
+  /**
+   * The red channel.
+   */
+  readonly r: number;
+
+  /**
+   * The green channel.
+   */
+  readonly g: number;
+
+  /**
+   * The blue channel.
+   */
+  readonly b: number;
+
+  /**
+   * The alpha channel.
+   */
+  readonly a?: number;
+
+  /**
+   * Whether any of the channels have been transformed by the color parser.
+   */
+  readonly isTransformed?: boolean;
+
+  /**
+   * Whether the color is the fallback color, which is used when the input is invalid.
+   */
+  readonly isFallback?: boolean;
+};

package/src/utils/channels.ts

@@ -0,0 +1,84 @@
+import { N, O } from "@auaust/primitive-kit";
+import type { ColorChannels } from "~/types";
+
+export function isRgbChannel(value: unknown): value is number {
+  return N.is(value) && N.isBetween(value, 0, 255);
+}
+
+export function toRgbChannel(value: number | undefined | null): number {
+  return N.clamp(N.round(value), 0, 255);
+}
+
+export function isAlphaChannel(value: unknown): value is number {
+  return N.is(value) && N.isBetween(value, 0, 1);
+}
+
+export function toAlphaChannel(value: number | undefined | null): number {
+  return N.is(value) ? N.clamp(value, 0, 1) : 1;
+}
+
+export function isColorChannels(value: unknown): value is ColorChannels {
+  return (
+    O.is(value, false) &&
+    isRgbChannel(value.r) &&
+    isRgbChannel(value.g) &&
+    isRgbChannel(value.b) &&
+    isAlphaChannel(value.a ?? 1)
+  );
+}
+
+/**
+ * Formats the input into a readonly object of color channels.
+ *
+ * It clamps the values to the valid range and sets the alpha channel to 1 if not provided.
+ * If the passed `isTransformed` isn't already `true`, it will set it to `true` if any of the values were clamped.
+ * If some channels are missing, it will return the fallback color.
+ */
+export function toColorChannels(value: ColorChannels): Required<ColorChannels>;
+export function toColorChannels(
+  r: number,
+  g: number,
+  b: number,
+  a?: number | null,
+  isTransformed?: boolean,
+  isFallback?: boolean
+): Required<ColorChannels>;
+export function toColorChannels(
+  r: number | ColorChannels,
+  g?: number,
+  b?: number,
+  a?: number | null,
+  isTransformed?: boolean,
+  isFallback?: boolean
+): Required<ColorChannels> {
+  if (O.is(r, false)) {
+    ({ r, g, b, a, isTransformed, isFallback } = r);
+  }
+
+  const finalR = toRgbChannel(r);
+  const finalG = toRgbChannel(g);
+  const finalB = toRgbChannel(b);
+
+  if (isNaN(finalR) || isNaN(finalG) || isNaN(finalB)) {
+    return fallbackColor;
+  }
+
+  const finalA = toAlphaChannel(a);
+
+  return O.freeze({
+    r: finalR,
+    g: finalG,
+    b: finalB,
+    a: finalA,
+    isTransformed: !!(
+      isTransformed ||
+      finalR !== r ||
+      finalG !== g ||
+      finalB !== b ||
+      finalA !== (a ?? 1)
+    ),
+    isFallback: !!isFallback,
+  });
+}
+
+export const fallbackColor = toColorChannels(0, 0, 0, 1, false, true);

package/src/utils/colors.ts

@@ -0,0 +1,72 @@
+import { Color } from "~/classes/Color";
+import type { ColorChannels, ColorType, ColorValue } from "~/types";
+import { fallbackColor, isColorChannels } from "./channels";
+import { isHex, parseHex } from "./hex";
+import { isNamedColor, parseNamedColor } from "./namedColors";
+import { couldBeRgb, isRgb, parseRgb } from "./rgb";
+import { channels } from "./symbols";
+
+/** Returns true if the value is any format of supported color. */
+export function isColor(value: unknown): value is ColorValue {
+  return type(value) !== undefined;
+}
+
+/** Returns the color type of the value, or undefined if it's not a color. */
+export function type(value: unknown): ColorType | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value instanceof Color) {
+    return "color";
+  }
+
+  if (isNamedColor(value)) {
+    return "named";
+  }
+
+  if (isHex(value)) {
+    return "hex";
+  }
+
+  if (isRgb(value)) {
+    return "rgb";
+  }
+
+  if (isColorChannels(value)) {
+    return "channels";
+  }
+
+  return undefined;
+}
+
+/** Tries to parse the value as a color. If it fails, returns the fallback color. */
+export function parseColor(value: unknown): ColorChannels {
+  if (!value) {
+    return fallbackColor;
+  }
+
+  if (value instanceof Color) {
+    return value[channels];
+  }
+
+  if (isColorChannels(value)) {
+    return value;
+  }
+
+  if (isNamedColor(value)) {
+    return parseNamedColor(value);
+  }
+
+  if (isHex(value)) {
+    return parseHex(value);
+  }
+
+  if (couldBeRgb(value)) {
+    // It might not be a valid RGB, in which case `parseRgb` is responsible for returning the fallback color
+    // In case more color types are added, it might be required to only return the result of `parseRgb` if `isFallback` is false
+    return parseRgb(value);
+  }
+
+  return fallbackColor;
+}

package/src/utils/distance.ts

@@ -0,0 +1,15 @@
+import type { ColorChannels } from "~/types";
+
+/** Calculate the distance between two colors. It is mostly useful for comparing distances between colors, but the value itself is not very meaningful. */
+export function distance(
+  a: ColorChannels,
+  b: ColorChannels,
+  alpha = false
+): number {
+  return Math.sqrt(
+    Math.pow(a.r - b.r, 2) +
+      Math.pow(a.g - b.g, 2) +
+      Math.pow(a.b - b.b, 2) +
+      (alpha ? Math.pow((a.a ?? 1) - (b.a ?? 1), 2) : 0)
+  );
+}

package/src/utils/hex.ts

@@ -0,0 +1,75 @@
+import { N, S } from "@auaust/primitive-kit";
+import type { ColorChannels, Hex } from "~/types";
+import { toColorChannels, toRgbChannel } from "./channels";
+
+const hexadecimalRegex = /^[0-9a-f]+$/i;
+
+/**
+ * Whether the input is a valid HEX color. With or without the alpha channel, and with single or double digits.
+ *
+ * It may or may not start with a hash character, which will be ignored.
+ */
+export function isHex(value: unknown): value is Hex {
+  value = S.is(value) && (value.startsWith("#") ? value.slice(1) : value);
+
+  if (!S.isStrict(value)) {
+    return false;
+  }
+
+  switch (value.length) {
+    case 3: // RGB
+    case 4: // RGBA
+    case 6: // RRGGBB
+    case 8: // RRGGBBAA
+      return hexadecimalRegex.test(value);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Parses a hex string into an object of color channels.
+ *
+ * The input must already be a valid HEX color, otherwise the result will be unexpected.
+ */
+export function parseHex(value: Hex): ColorChannels {
+  value = value.startsWith("#") ? value.slice(1) : value;
+
+  const isShort = value.length < 6;
+  const hasAlpha = isShort ? value.length === 4 : value.length === 8;
+
+  const r = parseInt(isShort ? value[0].repeat(2) : value.slice(0, 2), 16);
+  const g = parseInt(isShort ? value[1].repeat(2) : value.slice(2, 4), 16);
+  const b = parseInt(isShort ? value[2].repeat(2) : value.slice(4, 6), 16);
+  const a = hasAlpha
+    ? parseInt(isShort ? value[3].repeat(2) : value.slice(6, 8), 16) / 255
+    : 1;
+
+  return toColorChannels(r, g, b, a);
+}
+
+/**
+ * Returns the corresponding hex string of a color channels object.
+ *
+ * If the alpha channel is 1, it will be omitted.
+ */
+export function toHex(channels: ColorChannels): Hex {
+  const { r, g, b, a } = channels;
+
+  return (
+    "#" +
+    (
+      (1 << 24) +
+      (toRgbChannel(r) << 16) +
+      (toRgbChannel(g) << 8) +
+      toRgbChannel(b)
+    )
+      .toString(16)
+      .substring(1) +
+    (N.is(a) && a < 1
+      ? N.round(N.max(0, a) * 255)
+          .toString(16)
+          .padStart(2, "0")
+      : "")
+  );
+}