@auaust/jaune 0.0.0 → 0.0.2

package/README.md

@@ -0,0 +1,30 @@
+###### AUAUST LIBRARIES — JavaScript — jaune
+
+> This repository is made public to open the codebase to contributors.
+> When contributing to this repo, you agree to assign your copyrights to AUAUST.
+
+# jaune
+
+A toolkit for working with colors in JavaScript.
+
+## Installation
+
+```sh
+pnpm add @auaust/jaune
+```
+
+or if you prefer Yarn:
+
+```sh
+yarn add @auaust/jaune
+```
+
+## Environment Support
+
+`jaune` is compatible with all modern browsers. Since it doesn't use any advanced APIs, it is likely to work on older browsers as well, but it hasn't been tested. If it doesn't work on your browser but you think it should, please feel free to contribute!
+
+It also works in Node.js environments, and is fully implemented in TypeScript.
+
+## Sponsor
+
+This library is a project by us, [AUAUST](https://auaust.ch/). We sponsor ourselves!

package/dist/index-VyiURM-J.d.cts

@@ -0,0 +1,472 @@
+import { Writable } from 'type-fest';
+
+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.
+ */
+type ColorType = keyof ColorTypeMap;
+/** Represents a color in any of the various supported formats. */
+type ColorValue = ColorTypeMap[ColorType];
+/** A HEX color string. It must start with a hash (#) character followed by 3, 4, 6, or 8 hexadecimal digits. */
+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.
+ */
+type Rgb = readonly [r: number, g: number, b: number, a?: number] | readonly number[];
+/**
+ * A CSS color name.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+ */
+type NamedColor = keyof typeof namedColorsMap;
+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.
+ */
+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;
+};
+
+declare function isRgbChannel(value: unknown): value is number;
+declare function toRgbChannel(value: number | undefined | null): number;
+declare function isAlphaChannel(value: unknown): value is number;
+declare function toAlphaChannel(value: number | undefined | null): number;
+declare function isColorChannels(value: unknown): value is ColorChannels;
+/**
+ * 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.
+ */
+declare function toColorChannels(value: ColorChannels): Required<ColorChannels>;
+declare function toColorChannels(r: number, g: number, b: number, a?: number | null, isTransformed?: boolean, isFallback?: boolean): Required<ColorChannels>;
+declare const fallbackColor: Required<ColorChannels>;
+
+/** Returns true if the value is any format of supported color. */
+declare function isColor(value: unknown): value is ColorValue;
+/** Returns the color type of the value, or undefined if it's not a color. */
+declare function type(value: unknown): ColorType | undefined;
+/** Tries to parse the value as a color. If it fails, returns the fallback color. */
+declare function parseColor(value: unknown): ColorChannels;
+
+/**
+ * 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.
+ */
+declare function isHex(value: unknown): value is Hex;
+/**
+ * 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.
+ */
+declare function parseHex(value: Hex): ColorChannels;
+/**
+ * Returns the corresponding hex string of a color channels object.
+ *
+ * If the alpha channel is 1, it will be omitted.
+ */
+declare function toHex(channels: ColorChannels): Hex;
+
+/**
+ * A map of named colors and their HEX values.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+ */
+declare const namedColorsMap: Readonly<{
+    aliceblue: "#f0f8ffff";
+    antiquewhite: "#faebd7ff";
+    aqua: "#00ffffff";
+    aquamarine: "#7fffd4ff";
+    azure: "#f0ffffff";
+    beige: "#f5f5dcff";
+    bisque: "#ffe4c4ff";
+    black: "#000000ff";
+    blanchedalmond: "#ffebcdff";
+    blue: "#0000ffff";
+    blueviolet: "#8a2be2ff";
+    brown: "#a52a2aff";
+    burlywood: "#deb887ff";
+    cadetblue: "#5f9ea0ff";
+    chartreuse: "#7fff00ff";
+    chocolate: "#d2691eff";
+    coral: "#ff7f50ff";
+    cornflowerblue: "#6495edff";
+    cornsilk: "#fff8dcff";
+    crimson: "#dc143cff";
+    cyan: "#00ffffff";
+    darkblue: "#00008bff";
+    darkcyan: "#008b8bff";
+    darkgoldenrod: "#b8860bff";
+    darkgray: "#a9a9a9ff";
+    darkgreen: "#006400ff";
+    darkgrey: "#a9a9a9ff";
+    darkkhaki: "#bdb76bff";
+    darkmagenta: "#8b008bff";
+    darkolivegreen: "#556b2fff";
+    darkorange: "#ff8c00ff";
+    darkorchid: "#9932ccff";
+    darkred: "#8b0000ff";
+    darksalmon: "#e9967aff";
+    darkseagreen: "#8fbc8fff";
+    darkslateblue: "#483d8bff";
+    darkslategray: "#2f4f4fff";
+    darkslategrey: "#2f4f4fff";
+    darkturquoise: "#00ced1ff";
+    darkviolet: "#9400d3ff";
+    deeppink: "#ff1493ff";
+    deepskyblue: "#00bfffff";
+    dimgray: "#696969ff";
+    dimgrey: "#696969ff";
+    dodgerblue: "#1e90ffff";
+    firebrick: "#b22222ff";
+    floralwhite: "#fffaf0ff";
+    forestgreen: "#228b22ff";
+    fuchsia: "#ff00ffff";
+    gainsboro: "#dcdcdcff";
+    ghostwhite: "#f8f8ffff";
+    gold: "#ffd700ff";
+    goldenrod: "#daa520ff";
+    gray: "#808080ff";
+    green: "#008000ff";
+    greenyellow: "#adff2fff";
+    grey: "#808080ff";
+    honeydew: "#f0fff0ff";
+    hotpink: "#ff69b4ff";
+    indianred: "#cd5c5cff";
+    indigo: "#4b0082ff";
+    ivory: "#fffff0ff";
+    khaki: "#f0e68cff";
+    lavender: "#e6e6faff";
+    lavenderblush: "#fff0f5ff";
+    lawngreen: "#7cfc00ff";
+    lemonchiffon: "#fffacdff";
+    lightblue: "#add8e6ff";
+    lightcoral: "#f08080ff";
+    lightcyan: "#e0ffffff";
+    lightgoldenrodyellow: "#fafad2ff";
+    lightgray: "#d3d3d3ff";
+    lightgreen: "#90ee90ff";
+    lightgrey: "#d3d3d3ff";
+    lightpink: "#ffb6c1ff";
+    lightsalmon: "#ffa07aff";
+    lightseagreen: "#20b2aaff";
+    lightskyblue: "#87cefaff";
+    lightslategray: "#778899ff";
+    lightslategrey: "#778899ff";
+    lightsteelblue: "#b0c4deff";
+    lightyellow: "#ffffe0ff";
+    lime: "#00ff00ff";
+    limegreen: "#32cd32ff";
+    linen: "#faf0e6ff";
+    magenta: "#ff00ffff";
+    maroon: "#800000ff";
+    mediumaquamarine: "#66cdaaff";
+    mediumblue: "#0000cdff";
+    mediumorchid: "#ba55d3ff";
+    mediumpurple: "#9370dbff";
+    mediumseagreen: "#3cb371ff";
+    mediumslateblue: "#7b68eeff";
+    mediumspringgreen: "#00fa9aff";
+    mediumturquoise: "#48d1ccff";
+    mediumvioletred: "#c71585ff";
+    midnightblue: "#191970ff";
+    mintcream: "#f5fffaff";
+    mistyrose: "#ffe4e1ff";
+    moccasin: "#ffe4b5ff";
+    navajowhite: "#ffdeadff";
+    navy: "#000080ff";
+    oldlace: "#fdf5e6ff";
+    olive: "#808000ff";
+    olivedrab: "#6b8e23ff";
+    orange: "#ffa500ff";
+    orangered: "#ff4500ff";
+    orchid: "#da70d6ff";
+    palegoldenrod: "#eee8aaff";
+    palegreen: "#98fb98ff";
+    paleturquoise: "#afeeeeff";
+    palevioletred: "#db7093ff";
+    papayawhip: "#ffefd5ff";
+    peachpuff: "#ffdab9ff";
+    peru: "#cd853fff";
+    pink: "#ffc0cbff";
+    plum: "#dda0ddff";
+    powderblue: "#b0e0e6ff";
+    purple: "#800080ff";
+    rebeccapurple: "#663399ff";
+    red: "#ff0000ff";
+    rosybrown: "#bc8f8fff";
+    royalblue: "#4169e1ff";
+    saddlebrown: "#8b4513ff";
+    salmon: "#fa8072ff";
+    sandybrown: "#f4a460ff";
+    seagreen: "#2e8b57ff";
+    seashell: "#fff5eeff";
+    sienna: "#a0522dff";
+    silver: "#c0c0c0ff";
+    skyblue: "#87ceebff";
+    slateblue: "#6a5acdff";
+    slategray: "#708090ff";
+    slategrey: "#708090ff";
+    snow: "#fffafaff";
+    springgreen: "#00ff7fff";
+    steelblue: "#4682b4ff";
+    tan: "#d2b48cff";
+    teal: "#008080ff";
+    thistle: "#d8bfd8ff";
+    tomato: "#ff6347ff";
+    transparent: "#00000000";
+    turquoise: "#40e0d0ff";
+    violet: "#ee82eeff";
+    wheat: "#f5deb3ff";
+    white: "#ffffffff";
+    whitesmoke: "#f5f5f5ff";
+    yellow: "#ffff00ff";
+    yellowgreen: "#9acd32ff";
+}>;
+/**
+ * Whether the input is a valid named color.
+ *
+ * The check is case-sensitive.
+ */
+declare function isNamedColor(value: unknown): value is NamedColor;
+/**
+ * Returns the color channels from a named color. Must be a valid named color, already lowercased.
+ *
+ * @internal
+ */
+declare function namedColorChannels(name: NamedColor): ColorChannels;
+/**
+ * Returns the color channels from a named color.
+ */
+declare function parseNamedColor(name: MaybeNamedColor): ColorChannels;
+/**
+ * Returns the corresponding HEX value of a named color.
+ */
+declare function namedColorToHex(name: NamedColor): string;
+declare function namedColorToHex(name: MaybeNamedColor): string | undefined;
+/** Returns the closest named color to the passed color channels. */
+declare function closestNamedColor(channels: ColorChannels): NamedColor;
+/**
+ * Returns all the aliases of a named color.
+ */
+declare function namedColorAliases(name: NamedColor): readonly NamedColor[];
+/**
+ * Returns a boolean indicating whether two named colors are aliases.
+ */
+declare function isAliasToNamedColor(name: NamedColor, alias: NamedColor): boolean;
+
+type ChannelRange = number | [min: number, max: number];
+/**
+ * Generates a random color.
+ *
+ * Specific values or ranges can be provided for each channel.
+ * If a range is provided, the value will be randomly selected from within that range.
+ * If a single value is provided, that value will be used for the channel.
+ * If no value is provided, the channel will be randomly selected from 0 to 255 for RGB channels and be set to 1 for the alpha channel.
+ */
+declare function random({ r, g, b, a, }?: {
+    r?: ChannelRange;
+    g?: ChannelRange;
+    b?: ChannelRange;
+    a?: ChannelRange;
+}): ColorChannels;
+
+/**
+ * Whether the input is a valid RGB color.
+ */
+declare function isRgb(value: unknown): value is Rgb;
+/**
+ * Whether the input could be a valid RGB color.
+ * As in, it checks if the input is an array of numbers without validating the values range.
+ */
+declare function couldBeRgb(value: unknown): value is Rgb;
+/**
+ * Parses a RGB tuple into an object of color channels.
+ *
+ * The input must already be a valid RGB tuple, otherwise the result will be unexpected.
+ */
+declare function parseRgb(value: Rgb): ColorChannels;
+/**
+ * Returns the corresponding RGB tuple of a color channels object.
+ */
+declare function toRgb(channels: ColorChannels): Rgb;
+
+/**
+ * Used to privately store the cached channels of a color.
+ */
+declare const channels: unique symbol;
+/**
+ * Used to privately store the cached data of a color.
+ */
+declare const cache: unique symbol;
+
+declare class Color {
+    protected [channels]: Required<Writable<ColorChannels>>;
+    protected [cache]: Map<string | Function, any>;
+    constructor(value: ColorChannels);
+    static from(value: ColorValue): Color;
+    static from(red: number, green: number, blue: number, alpha?: number): Color;
+    static fromChannels(channels: ColorChannels): Color;
+    static fromRgb(rgb: Rgb): Color;
+    static fromHex(hex: string): Color;
+    static fromName(name: MaybeNamedColor): Color;
+    static random(presets?: Parameters<typeof random>[0]): Color;
+    /**
+     * 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: typeof type;
+    /** Returns a boolean indicating whether the passed value is a color. */
+    static isColor: typeof isColor;
+    /** @alias Color#isColor */
+    static is: typeof isColor;
+    /** Returns a boolean indicating whether the passed value is a HEX color string. */
+    static isHex: typeof isHex;
+    /** Returns a boolean indicating whether the passed value is a named color. */
+    static isNamedColor: typeof isNamedColor;
+    /** Returns a boolean indicating whether the passed value is a color channel object. */
+    static isColorChannels: typeof isColorChannels;
+    /** Returns a boolean indicating whether the passed value is a RGB color tuple. */
+    static isRgb: typeof isRgb;
+    /** Returns all the aliases of a named color, including the name itself. */
+    static namedColorAliases: typeof namedColorAliases;
+    /** Returns a boolean whether two named colors are aliases, meaning they have the same HEX value. */
+    static isAliasToNamedColor: typeof 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;
+    /** Returns a new `Color` instance with the passed channels overriding the current ones. */
+    with(value: Partial<Pick<ColorChannels, "r" | "g" | "b" | "a">>): Color;
+    /** Returns a new `Color` instance with the specified red channel. */
+    withRed(value: number): Color;
+    /** Returns a new `Color` instance with the specified green channel. */
+    withGreen(value: number): Color;
+    /** Returns a new `Color` instance with the specified blue channel. */
+    withBlue(value: number): Color;
+    /** Returns a new `Color` instance with the specified alpha channel. */
+    withAlpha(value: number): Color;
+    private updated;
+    set(channel: "r" | "g" | "b" | "a", value: number): this;
+    /** The red channel of the color. */
+    get red(): number;
+    /** @see Color#red */
+    get r(): number;
+    set red(value: number);
+    setRed(value: number): this;
+    /** The green channel of the color. */
+    get green(): number;
+    /** @see Color#green */
+    get g(): number;
+    set green(value: number);
+    setGreen(value: number): this;
+    /** The blue channel of the color. */
+    get blue(): number;
+    /** @see Color#blue */
+    get b(): number;
+    set blue(value: number);
+    setBlue(value: number): this;
+    /** The alpha channel of the color. */
+    get alpha(): number;
+    /** @see Color#alpha */
+    get a(): number;
+    set alpha(value: number);
+    setAlpha(value: number): this;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Helper to cache data until the channels are updated. */
+    private memoize;
+    /** Checks if the color is fully opaque. */
+    get isOpaque(): boolean;
+    /** Checks if the color is fully transparent. */
+    get isTransparent(): boolean;
+    /** Checks if the color is at least partially transparent. */
+    get isTranslucent(): boolean;
+    /**
+     * 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;
+    /** The relative brightness of the color. */
+    get brightness(): number;
+    /** Whether the color is considered bright. */
+    get isBright(): boolean;
+    /** Whether the color is considered dark. */
+    get isDark(): boolean;
+    /** Whether the color is brighter than the passed threshold or color. */
+    isBrighterThan(threshold: Color | number): boolean;
+    /** Whether the color is darker than the passed threshold or color. */
+    isDarkerThan(threshold: Color | number): boolean;
+    /** Returns the relative luminance of the color. */
+    get luminance(): number;
+    /** Returns the contrast ratio between this color and another. */
+    contrast(color: ColorValue): number;
+    /** Returns the distance between this color and another. If `alpha` is `true`, the alpha channel is included in the calculation. */
+    distance(color: ColorValue, alpha?: boolean): number;
+    /** Returns a new color with the grayscale equivalent of the current color, preserving the alpha channel. */
+    toGrayscale(): Color;
+    toHex(): string;
+    toRgb(): Rgb;
+    toChannels(): ColorChannels;
+    toString(): string;
+    valueOf(): string;
+    [Symbol.toPrimitive](): string;
+    toJSON(): string;
+}
+
+export { toRgb as A, Color as B, type ColorChannels as C, type ColorType as D, type ColorValue as E, type Hex as H, type MaybeNamedColor as M, type NamedColor as N, type Rgb as R, isColorChannels as a, isRgbChannel as b, toColorChannels as c, toRgbChannel as d, isColor as e, fallbackColor as f, type as g, isHex as h, isAlphaChannel as i, parseHex as j, toHex as k, closestNamedColor as l, isAliasToNamedColor as m, isNamedColor as n, namedColorAliases as o, parseColor as p, namedColorChannels as q, namedColorsMap as r, namedColorToHex as s, toAlphaChannel as t, parseNamedColor as u, random as v, type ChannelRange as w, couldBeRgb as x, isRgb as y, parseRgb as z };