colorizr 3.0.2 → 3.0.4

package/README.md

@@ -241,7 +241,7 @@ palette('#ff0044', { type: 'monochromatic' });
 // ['#ff99b4', '#ff5582', '#ff1150', '#cc0036', '#880024', '#440012']
 ```
 
-**scheme(input: string, type: Scheme): string[]**  
+**scheme(input: string, type: SchemeOptions): string[]**  
 Get a color scheme.
 
 ```typescript
@@ -251,30 +251,49 @@ const complementary = scheme('rgb(255 0 68)'); // ['#ff0044', '#00ffbb']
 const triadic = scheme('#ff0044', 'triadic'); // ['#ff0044', '#44ff00', '#0044ff']
 ```
 
-**swatch(input: string, variant?: 'up' | 'down'): string[]**  
-Generate a color swatch with ten shades.  
-The `variant` can be used to generate a lighter or darker swatch.
+**swatch(input: string, options?: SwatchOptions): Swatch**  
+Generate a color swatch with ten shades, from lightest (50) to darkest (900).
 
 ```typescript
 import { swatch } from 'colorizr';
 
-const colors = swatch('#ff0044');
-/* [
-  "#ffccda",
-  "#ff99b4",
-  "#ff668f",
-  "#ff3369",
-  "#ff0044",
-  "#cc0036",
-  "#990029",
-  "#66001b",
-  "#33000e",
-  "#1a0007",
-] */
+swatch('#ff0044');
+/*
+{
+  "50": "#ff9aa7",
+  "100": "#ff7a8a",
+  "200": "#ff586f",
+  "300": "#ff3053",
+  "400": "#ed0039",
+  "500": "#cd001b",
+  "600": "#b30000",
+  "700": "#970000",
+  "800": "#7a0000",
+  "900": "#5b0000",
+}
+*/
+
+swatch('#ff0044', { mode: 'light' });
+/*
+{
+  "50": "#ffd0d8",
+  "100": "#ffa5b0",
+  "200": "#ff7a8a",
+  "300": "#ff4c65",
+  "400": "#f90041",
+  "500": "#cd001b",
+  "600": "#ba0000",
+  "700": "#a50000",
+  "800": "#900000",
+  "900": "#790000",
+}
+*/
 ```
 
 ### Converters
 
+The default precision is 5.
+
 **convert(input: string, format: ColorType): string**  
 Convert a color string to another format.
 
@@ -461,7 +480,7 @@ rgb2hsl({ r: 255, g: 0, b: 68 }); // { h: 344, s: 100, l: 50 }
 rgb2hsl([255, 0, 68]); // { h: 344, s: 100, l: 50 }
 ```
 
-**rgb2oklab(input: RGB | ColorTuple, precision: number): LAB**  
+**rgb2oklab(input: RGB | ColorTuple, precision?: number): LAB**  
 Convert RGB to OKLAB.
 
 ```typescript
@@ -471,7 +490,7 @@ rgb2oklab({ r: 255, g: 0, b: 68 }); // { l: 0.63269, a: 0.23887, b: 0.08648 }
 rgb2oklab([255, 0, 68]); // { l: 0.63269, a: 0.23887, b: 0.08648 }
 ```
 
-**rgb2oklch(input: RGB | ColorTuple, precision: number): LCH**  
+**rgb2oklch(input: RGB | ColorTuple, precision?: number): LCH**  
 Convert RGB to OKLCH.
 
 ```typescript
@@ -525,7 +544,7 @@ extractColorParts('rgb(255 0 68)') // { model: 'rgb', r: 255, g: 0, b: 68 }
 extractColorParts('hsl(344 100% 50% / 90%)') // { alpha: 0.9, model: 'hsl', h: 344, g: 100, l: 50 }
 ```
 
-**formatCSS(input: HSL | RGB, options?: FormatOptions): string**  
+**formatCSS(input: HSL | RGB, options?: FormatCSSOptions): string**  
 Get a css string from a color object.
 
 ```typescript
@@ -595,7 +614,7 @@ import { removeAlphaFromHex } from 'colorizr';
 removeAlphaFromHex('#ff0044cc'); // '#ff0044'
 ```
 
-**textColor(input: string): string**  
+**textColor(input: string, options?: TextColorOptions): string**  
 Get a contrasting color (black or white) for the input color.
 
 ```typescript

package/dist/index.d.mts

@@ -4,7 +4,7 @@ type ColorModelKey = 'hsl' | 'oklab' | 'oklch' | 'rgb';
 type ColorModelKeys<TModel extends ColorModelKey> = TModel extends 'hsl' ? keyof Omit<HSL, 'alpha'> : TModel extends 'oklab' ? keyof Omit<LAB, 'alpha'> : TModel extends 'oklch' ? keyof Omit<LCH, 'alpha'> : TModel extends 'rgb' ? keyof Omit<RGB, 'alpha'> : never;
 type ColorKeysTuple = [string, string, string];
 type ColorTuple = [number, number, number];
-type ConverterParameters<TModel extends ColorModel> = TModel | ColorTuple;
+type ColorTokens = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 interface Colors {
     alpha: Alpha;
     hex: HEX;
@@ -14,6 +14,7 @@ interface Colors {
     rgb: RGB;
     type: ColorType;
 }
+type ConverterParameters<TModel extends ColorModel> = TModel | ColorTuple;
 type Alpha = number;
 type Amount = number;
 type Degrees = number;
@@ -54,9 +55,11 @@ interface Analysis {
 }
 type PlainObject<T = any> = Record<string, T>;
 
-interface Options$1 {
+interface ColorizrOptions {
     /**
-     * The output color type
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
      */
     format?: ColorType;
 }
@@ -68,7 +71,7 @@ declare class Colorizr {
     oklch: LCH;
     rgb: RGB;
     type: ColorType;
-    constructor(color: string | HSL | LAB | LCH | RGB, options?: Options$1);
+    constructor(color: string | HSL | LAB | LCH | RGB, options?: ColorizrOptions);
     /**
      * Get css string
      */
@@ -203,10 +206,13 @@ type ExtractColorPartsReturn = {
  */
 declare function extractColorParts(input: string): ExtractColorPartsReturn;
 
-interface FormatOptions {
+interface FormatCSSOptions {
+    /**
+     * The alpha value of the color.
+     */
     alpha?: Alpha;
     /**
-     * The output color type.
+     * Output color format.
      * @default 'hex'
      */
     format?: ColorType;
@@ -217,12 +223,13 @@ interface FormatOptions {
     precision?: number;
     /**
      * The separator between the values.
+     *
      * oklab and oklch always use space as a separator.
      * @default ' '
      */
     separator?: string;
 }
-declare function formatCSS<T extends ColorModel | HEX>(input: T, options?: FormatOptions): string;
+declare function formatCSS<T extends ColorModel | HEX>(input: T, options?: FormatCSSOptions): string;
 
 declare function formatHex(input: string): HEX;
 
@@ -245,14 +252,36 @@ declare function luminance(input: string): number;
 declare function name(input: string): string;
 
 interface PaletteOptions {
+    /**
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
+     */
     format?: ColorType;
+    /**
+     * Adjusts the lightness of the base color before generating the palette.
+     *
+     * Value should be between 0 and 100.
+     */
     lightness?: number;
+    /**
+     * Adjusts the saturation of the base color before generating the palette.
+     *
+     * Value should be between 0 and 100.
+     */
     saturation?: number;
     /**
-     * The number of colors to generate
+     * The number of colors to generate in the palette.
+     *
+     * Minimum value is 2.
      * @default 6
      */
     size?: number;
+    /**
+     * Generate a monochromatic palette.
+     *
+     * For more options, use the `swatch` function.
+     */
     type?: 'monochromatic';
 }
 declare function palette(input: string, options?: PaletteOptions): string[];
@@ -296,6 +325,11 @@ declare function saturate(input: string, amount: number, format?: ColorType): st
 
 type Scheme = 'analogous' | 'complementary' | 'rectangle' | 'split' | 'split-complementary' | 'square' | 'tetradic' | 'triadic';
 interface SchemeOptions {
+    /**
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
+     */
     format?: ColorType;
     /**
      * The type of scheme to generate.
@@ -308,25 +342,55 @@ interface SchemeOptions {
  */
 declare function scheme(input: string, typeOrOptions?: Scheme | SchemeOptions): string[];
 
-type ColorTokens = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 type Swatch = {
     [key in ColorTokens]: string;
 };
+type SwatchVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
 interface SwatchOptions {
+    /**
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
+     */
     format?: ColorType;
     /**
-     * The scale of the swatch.
-     * Linear scale will have equal distance between each shade.
+     * The mode of the swatch.
+     * - 'light': Focuses on lighter tones starting from a higher lightness.
+     * - 'dark': Focuses on darker tones starting from a lower lightness.
+     *
+     * If omitted, a balanced palette is generated.
+     */
+    mode?: 'light' | 'dark';
+    /**
+     * Generate a monochromatic swatch.
+     *
+     * Disable chroma adjustments for all shades.
+     * @default false
+     */
+    monochromatic?: boolean;
+    /**
+     * Determines the scale type for the swatch.
+     * - 'linear': Shades are distributed with equal lightness intervals.
+     * - 'dynamic': Shades are distributed adaptively based on the input color.
      * @default 'dynamic'
      */
     scale?: 'dynamic' | 'linear';
+    /**
+     * The variant of the swatch.
+     * - 'deep': Generates rich and bold tones with significantly reduced lightness.
+     * - 'neutral': Generates muted tones by reducing chroma.
+     * - 'pastel': Produces soft and airy tones with significant chroma reduction.
+     * - 'subtle': Creates extremely desaturated tones, close to grayscale.
+     * - 'vibrant': Enhances chroma for bold and striking tones.
+     */
+    variant?: SwatchVariant;
 }
 /**
  * Generate a palette of shades of a color
  */
 declare function swatch(input: string, options?: SwatchOptions): Swatch;
 
-interface Options {
+interface TextColorOptions {
     /**
      * The dark color to return if the input is light.
      * @default '#000000'
@@ -339,6 +403,7 @@ interface Options {
     lightColor?: string;
     /**
      * The threshold to determine if the color is light or dark.
+     *
      * A number between 0 and 255.
      * @default 128
      */
@@ -347,7 +412,7 @@ interface Options {
 /**
  * Get the contrasted color for a given hex.
  */
-declare function textColor(input: string, options?: Options): string;
+declare function textColor(input: string, options?: TextColorOptions): string;
 
 /**
  * Increase the color transparency.
@@ -455,4 +520,4 @@ declare function isLCH(input: unknown): input is LCH;
  */
 declare function isRGB(input: unknown): input is RGB;
 
-export { type Alpha, type Amount, type Analysis, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorTuple, type ColorType, type Colors, type ConverterParameters, type Degrees, type HEX, type HSL, type LAB, type LCH, type PlainObject, type RGB, addAlphaToHex, brightnessDifference, chroma, colorDifference, compare, contrast, convert, convertAlphaToHex, darken, Colorizr as default, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getOkLCHMaxChroma, getP3Color, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hexadecimalToNumber, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, isHSL, isHex, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scheme, swatch, textColor, transparentize };
+export { type Alpha, type Amount, type Analysis, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorTokens, type ColorTuple, type ColorType, type ColorizrOptions, type Colors, type ConverterParameters, type Degrees, type FormatCSSOptions, type HEX, type HSL, type LAB, type LCH, type PaletteOptions, type PlainObject, type RGB, type Scheme, type SchemeOptions, type Swatch, type SwatchOptions, type SwatchVariant, type TextColorOptions, addAlphaToHex, brightnessDifference, chroma, colorDifference, compare, contrast, convert, convertAlphaToHex, darken, Colorizr as default, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getOkLCHMaxChroma, getP3Color, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hexadecimalToNumber, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, isHSL, isHex, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scheme, swatch, textColor, transparentize };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ type ColorModelKey = 'hsl' | 'oklab' | 'oklch' | 'rgb';
 type ColorModelKeys<TModel extends ColorModelKey> = TModel extends 'hsl' ? keyof Omit<HSL, 'alpha'> : TModel extends 'oklab' ? keyof Omit<LAB, 'alpha'> : TModel extends 'oklch' ? keyof Omit<LCH, 'alpha'> : TModel extends 'rgb' ? keyof Omit<RGB, 'alpha'> : never;
 type ColorKeysTuple = [string, string, string];
 type ColorTuple = [number, number, number];
-type ConverterParameters<TModel extends ColorModel> = TModel | ColorTuple;
+type ColorTokens = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 interface Colors {
     alpha: Alpha;
     hex: HEX;
@@ -14,6 +14,7 @@ interface Colors {
     rgb: RGB;
     type: ColorType;
 }
+type ConverterParameters<TModel extends ColorModel> = TModel | ColorTuple;
 type Alpha = number;
 type Amount = number;
 type Degrees = number;
@@ -54,9 +55,11 @@ interface Analysis {
 }
 type PlainObject<T = any> = Record<string, T>;
 
-interface Options$1 {
+interface ColorizrOptions {
     /**
-     * The output color type
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
      */
     format?: ColorType;
 }
@@ -68,7 +71,7 @@ declare class Colorizr {
     oklch: LCH;
     rgb: RGB;
     type: ColorType;
-    constructor(color: string | HSL | LAB | LCH | RGB, options?: Options$1);
+    constructor(color: string | HSL | LAB | LCH | RGB, options?: ColorizrOptions);
     /**
      * Get css string
      */
@@ -203,10 +206,13 @@ type ExtractColorPartsReturn = {
  */
 declare function extractColorParts(input: string): ExtractColorPartsReturn;
 
-interface FormatOptions {
+interface FormatCSSOptions {
+    /**
+     * The alpha value of the color.
+     */
     alpha?: Alpha;
     /**
-     * The output color type.
+     * Output color format.
      * @default 'hex'
      */
     format?: ColorType;
@@ -217,12 +223,13 @@ interface FormatOptions {
     precision?: number;
     /**
      * The separator between the values.
+     *
      * oklab and oklch always use space as a separator.
      * @default ' '
      */
     separator?: string;
 }
-declare function formatCSS<T extends ColorModel | HEX>(input: T, options?: FormatOptions): string;
+declare function formatCSS<T extends ColorModel | HEX>(input: T, options?: FormatCSSOptions): string;
 
 declare function formatHex(input: string): HEX;
 
@@ -245,14 +252,36 @@ declare function luminance(input: string): number;
 declare function name(input: string): string;
 
 interface PaletteOptions {
+    /**
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
+     */
     format?: ColorType;
+    /**
+     * Adjusts the lightness of the base color before generating the palette.
+     *
+     * Value should be between 0 and 100.
+     */
     lightness?: number;
+    /**
+     * Adjusts the saturation of the base color before generating the palette.
+     *
+     * Value should be between 0 and 100.
+     */
     saturation?: number;
     /**
-     * The number of colors to generate
+     * The number of colors to generate in the palette.
+     *
+     * Minimum value is 2.
      * @default 6
      */
     size?: number;
+    /**
+     * Generate a monochromatic palette.
+     *
+     * For more options, use the `swatch` function.
+     */
     type?: 'monochromatic';
 }
 declare function palette(input: string, options?: PaletteOptions): string[];
@@ -296,6 +325,11 @@ declare function saturate(input: string, amount: number, format?: ColorType): st
 
 type Scheme = 'analogous' | 'complementary' | 'rectangle' | 'split' | 'split-complementary' | 'square' | 'tetradic' | 'triadic';
 interface SchemeOptions {
+    /**
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
+     */
     format?: ColorType;
     /**
      * The type of scheme to generate.
@@ -308,25 +342,55 @@ interface SchemeOptions {
  */
 declare function scheme(input: string, typeOrOptions?: Scheme | SchemeOptions): string[];
 
-type ColorTokens = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 type Swatch = {
     [key in ColorTokens]: string;
 };
+type SwatchVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
 interface SwatchOptions {
+    /**
+     * Output color format.
+     *
+     * If not specified, the output will use the same format as the input color.
+     */
     format?: ColorType;
     /**
-     * The scale of the swatch.
-     * Linear scale will have equal distance between each shade.
+     * The mode of the swatch.
+     * - 'light': Focuses on lighter tones starting from a higher lightness.
+     * - 'dark': Focuses on darker tones starting from a lower lightness.
+     *
+     * If omitted, a balanced palette is generated.
+     */
+    mode?: 'light' | 'dark';
+    /**
+     * Generate a monochromatic swatch.
+     *
+     * Disable chroma adjustments for all shades.
+     * @default false
+     */
+    monochromatic?: boolean;
+    /**
+     * Determines the scale type for the swatch.
+     * - 'linear': Shades are distributed with equal lightness intervals.
+     * - 'dynamic': Shades are distributed adaptively based on the input color.
      * @default 'dynamic'
      */
     scale?: 'dynamic' | 'linear';
+    /**
+     * The variant of the swatch.
+     * - 'deep': Generates rich and bold tones with significantly reduced lightness.
+     * - 'neutral': Generates muted tones by reducing chroma.
+     * - 'pastel': Produces soft and airy tones with significant chroma reduction.
+     * - 'subtle': Creates extremely desaturated tones, close to grayscale.
+     * - 'vibrant': Enhances chroma for bold and striking tones.
+     */
+    variant?: SwatchVariant;
 }
 /**
  * Generate a palette of shades of a color
  */
 declare function swatch(input: string, options?: SwatchOptions): Swatch;
 
-interface Options {
+interface TextColorOptions {
     /**
      * The dark color to return if the input is light.
      * @default '#000000'
@@ -339,6 +403,7 @@ interface Options {
     lightColor?: string;
     /**
      * The threshold to determine if the color is light or dark.
+     *
      * A number between 0 and 255.
      * @default 128
      */
@@ -347,7 +412,7 @@ interface Options {
 /**
  * Get the contrasted color for a given hex.
  */
-declare function textColor(input: string, options?: Options): string;
+declare function textColor(input: string, options?: TextColorOptions): string;
 
 /**
  * Increase the color transparency.
@@ -455,4 +520,4 @@ declare function isLCH(input: unknown): input is LCH;
  */
 declare function isRGB(input: unknown): input is RGB;
 
-export { type Alpha, type Amount, type Analysis, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorTuple, type ColorType, type Colors, type ConverterParameters, type Degrees, type HEX, type HSL, type LAB, type LCH, type PlainObject, type RGB, addAlphaToHex, brightnessDifference, chroma, colorDifference, compare, contrast, convert, convertAlphaToHex, darken, Colorizr as default, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getOkLCHMaxChroma, getP3Color, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hexadecimalToNumber, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, isHSL, isHex, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scheme, swatch, textColor, transparentize };
+export { type Alpha, type Amount, type Analysis, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorTokens, type ColorTuple, type ColorType, type ColorizrOptions, type Colors, type ConverterParameters, type Degrees, type FormatCSSOptions, type HEX, type HSL, type LAB, type LCH, type PaletteOptions, type PlainObject, type RGB, type Scheme, type SchemeOptions, type Swatch, type SwatchOptions, type SwatchVariant, type TextColorOptions, addAlphaToHex, brightnessDifference, chroma, colorDifference, compare, contrast, convert, convertAlphaToHex, darken, Colorizr as default, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getOkLCHMaxChroma, getP3Color, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hexadecimalToNumber, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, isHSL, isHex, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scheme, swatch, textColor, transparentize };