colorizr 3.0.0-0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Colorizr
 
-[![NPM version](https://badge.fury.io/js/colorizr.svg)](https://www.npmjs.com/package/colorizr) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/colorizr)](https://bundlephobia.com/result?p=colorizr) [![CI](https://github.com/gilbarbara/colorizr/actions/workflows/main.yml/badge.svg)](https://github.com/gilbarbara/colorizr/actions/workflows/main.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/6d686ce2a9f2a1a47d98/maintainability)](https://codeclimate.com/github/gilbarbara/colorizr/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/6d686ce2a9f2a1a47d98/test_coverage)](https://codeclimate.com/github/gilbarbara/colorizr/test_coverage)
+[![NPM version](https://badge.fury.io/js/colorizr.svg)](https://www.npmjs.com/package/colorizr) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/colorizr)](https://bundlephobia.com/result?p=colorizr) [![CI](https://github.com/gilbarbara/colorizr/actions/workflows/main.yml/badge.svg)](https://github.com/gilbarbara/colorizr/actions/workflows/main.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_colorizr&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gilbarbara_colorizr) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_colorizr&metric=coverage)](https://sonarcloud.io/summary/new_code?id=gilbarbara_colorizr)
 
 Color conversion, generation, manipulation, comparison, and analysis.
 
@@ -16,18 +16,20 @@ Color conversion, generation, manipulation, comparison, and analysis.
 **Install**
 
 ```bash
-npm install --save colorizr
+npm i colorizr
 ```
 
 ## Usage
 
+You can use all the functions standalone:
+
 ```typescript
 import { luminance } from 'colorizr';
 
 const lux = luminance('#ff0044'); // 0.2168
 ```
 
-Or you can create an instance to use all the methods for the selected color:
+Or you can create an instance to use all the methods for the same color:
 
 ```typescript
 import Colorizr from 'Colorizr';
@@ -44,10 +46,10 @@ colorInstance.opacity; // 1
 
 - [Info](#Info)
 - [Manipulators](#Manipulators)
-- [Utilities](#Utilities)
 - [Converters](#Converters)
 - [Generators](#Generators)
 - [Comparison](#Comparison)
+- [Utilities](#Utilities)
 - [Validators](#Validators)
 - [Class](#Class)
 
@@ -79,7 +81,7 @@ Get the name of a color. Return the hex code if it can't be named.
 ```typescript
 import { name } from 'colorizr';
 
-name('#ffc0cb', 10); // pink
+name('#ffc0cb'); // pink
 name('rgb(176 224 230)'); // 'powderblue'
 name('hsl(344 100 50)'); // #ff0044
 ```
@@ -90,29 +92,31 @@ Get the opacity of a color.
 ```typescript
 import { opacity } from 'colorizr';
 
-opacity('#ff0044'); 1
-opacity('rgb(255 0 68 / 90%)'); 0.9
-opacity('hsl(344 100 50 / 60%)'); 0.6
+opacity('#ff0044'); // 1
+opacity('rgb(255 0 68 / 90%)'); // 0.9
+opacity('hsl(344 100 50 / 60%)'); // 0.6
 ```
 
 ### Manipulators
 
-**lighten(input: string, alpha: number): string**  
+**lighten(input: string, amount: number): string**  
 Get a color with increased lightness.
 
 ```typescript
 import { lighten } from 'colorizr';
 
 lighten('#ff0044', 10); // #ff3369
+lighten('hsl(136 100% 50%)', 10); // hsl(136 100% 60%)
 ```
 
-**darken(input: string, alpha = 10): string**  
+**darken(input: string, amount: number): string**  
 Get a color with decreased lightness.
 
 ```typescript
 import { darken } from 'colorizr';
 
 darken('#ff0044', 10); // #cc0036
+darken('oklch(47.642% 0.29956 274.93693)', 10); // oklch(40.377% 0.25281 275.46794)
 ```
 
 **saturate(input: string, amount: number): string**  
@@ -132,6 +136,7 @@ Get a color with decreased saturation.
 import { desaturate } from 'colorizr';
 
 desaturate('#ff0044', 10); // #f20d4a
+desaturate('oklab(70.622% 0.1374 0.14283)', 10); // oklab(69.021% 0.12176 0.13721)
 ```
 
 **invert(input: string): string**  
@@ -159,8 +164,8 @@ Add opacity to a color
 ```typescript
 import { opacify } from 'colorizr';
 
-opacify('hsl(344, 100, 50)', 10); // rgba(255, 0, 68, 0.9)
-opacify('#ff0044', 50); // hsla(344, 100%, 50%, 0.5)
+opacify('hsl(344, 100, 50)', 0.9); // hsl(344 100 50 / 90%)
+opacify('#ff0044', 0.8); // #ff0044cc
 ```
 
 **transparentize(input: string, alpha: number, format?: ColorType): string**  
@@ -169,110 +174,8 @@ Increase/decrease the color opacity.
 ```typescript
 import { transparentize } from 'colorizr';
 
-transparentize('hsl(344, 100, 50)', 10); // rgba(255, 0, 68, 0.9)
-transparentize('#ff0044', 50, 'hsl'); // hsla(344, 100%, 50%, 0.5)
-```
-
-### Utilities
-
-**addAlphaToHex(input: string, alpha: number): string**  
-Add an alpha value to a hex string
-
-```typescript
-import { addAlphaToHex } from 'colorizr';
-
-addAlphaToHex('#ff0044', 0.9); // '#ff0044e6'
-addAlphaToHex('#ff0044cc', 0.9); // '#ff0044e6'
-```
-
-**convertAlphaToHex(input: number): string**  
-Convert an alpha value to a hex value.
-
-```typescript
-import { convertAlphaToHex } from 'colorizr';
-
-convertAlphaToHex(0.5); // '80'
-```
-
-**extractAlphaFromHex(input: string): number**  
-Extract the alpha value from a hex string
-
-```typescript
-import { extractAlphaFromHex } from 'colorizr';
-
-convertAlphaToHex('#ff004480'); // 0.5
-```
-
-**extractColorParts(input: string): ExtractColorPartsReturn**  
-Extract the color parts from a CSS color string.
-Hex colors are not supported.
-
-```typescript
-type ExtractColorPartsReturn = {
-  alpha?: number;
-  model: 'hsl' | 'oklab' | 'oklch' | 'rgb';
-} & Record<string, number>;
-
-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**  
-Get a css string from a color object.
-
-```typescript
-import { formatCSS } from 'colorizr';
-
-formatCSS({ h: 344, s: 100, l: 50 }, { format: 'rgb' }); // 'rgb(255, 0, 68)'
-formatCSS({ r: 255, g: 0, b: 68 }, { alpha: 0.5, format: 'hsl' }); // 'hsla(344, 100%, 50%, 0.5)'
-```
-
-**formatHex(input: string): string**  
-Format a short hex string of 3 (or 4) digits into 6 (or 8) digits.
-
-```typescript
-import { formatHex } from 'colorizr';
-
-formatHex('#07e'); // '#0077ee'
-formatHex('#f058'); // '#ff005588'
-```
-**parseCSS(input: string, format?: ColorType): string | HSL | RGB**  
-Parse a css string to hex, HSL, OKLAB, OKLCH, or RGB.  
-If the format isn't set, it will return the same format as the input.
-
-```typescript
-import { parseCSS } from 'colorizr';
-
-parseCSS('hsl(344 100% 50%)'); // { h: 344, l: 50, s: 100 }
-parseCSS('#ff0044', 'hsl'); // { h: 344, l: 50, s: 100 }
-```
-
-**random(): string**  
-Get a random color.
-
-```typescript
-import { random } from 'colorizr';
-
-random(); // '#b385e0'
-```
-
-**removeAlphaFromHex(input: string): string**  
-Remove the alpha value from a hex string
-
-```typescript
-import { removeAlphaFromHex } from 'colorizr';
-
-removeAlphaFromHex('#ff0044cc'); // '#ff0044'
-```
-
-**textColor(input: string): string**  
-Get a contrasting color (black or white) for the input color.
-
-```typescript
-import { textColor } from 'colorizr';
-
-textColor('#ff0044'); // #ffffff
-textColor('#fff800'); // #000000
+transparentize('hsl(344, 100, 50)', 10); // hsl(344 100 50 / 90%)
+transparentize('#ff0044', 50, 'hsl'); // #ff004480
 ```
 
 ### Comparison
@@ -292,7 +195,7 @@ Get the color difference between the two colors.
 ```typescript
 import { colorDifference } from 'colorizr';
 
-colorDifference('hsl(0, 0%, 100%)', '#f04'); // 442
+colorDifference('hsl(0 0% 100%)', '#f04'); // 442
 ```
 
 **compare(left: string, right: string): Analysis**  
@@ -321,7 +224,7 @@ Get the WCAG contrast ratio between two colors.
 ```typescript
 import { contrast } from 'colorizr';
 
-contrast('hsl(0, 0%, 100%)', 'rgb(255, 0, 68)'); // 3.94
+contrast('hsl(0 0% 100%)', 'rgb(255 0 68)'); // 3.94
 ```
 ### Generators
 
@@ -344,7 +247,7 @@ Get a color scheme.
 ```typescript
 import { scheme } from 'colorizr';
 
-const complementary = scheme('rgb(255, 0, 68)'); // ['#ff0044', '#00ffbb']
+const complementary = scheme('rgb(255 0 68)'); // ['#ff0044', '#00ffbb']
 const triadic = scheme('#ff0044', 'triadic'); // ['#ff0044', '#44ff00', '#0044ff']
 ```
 
@@ -373,7 +276,7 @@ const colors = swatch('#ff0044');
 ### Converters
 
 **convert(input: string, format: ColorType): string**  
-Convert a color string from one format to another.
+Convert a color string to another format.
 
 ```typescript
 import { convert } from 'colorizr';
@@ -418,7 +321,7 @@ import { hex2rgb } from 'colorizr';
 hex2rgb('#ff0044'); // { r: 255, g: 0, b: 68 }
 ```
 
-**hsl2hex(input: HSL | ColorTupple): string**  
+**hsl2hex(input: HSL | ColorTuple): string**  
 Convert HSL to HEX.
 
 ```typescript
@@ -428,7 +331,7 @@ hsl2hex({ h: 344, s: 100, l: 50 }); // '#ff0044'
 hsl2hex([344, 100, 50]); // '#ff0044'
 ```
 
-**hsl2oklab(input: HSL | ColorTupple, precision?: number): LAB**  
+**hsl2oklab(input: HSL | ColorTuple, precision?: number): LAB**  
 Convert HSL to OKLAB.
 
 ```typescript
@@ -438,7 +341,7 @@ hsl2oklab({ h: 344, s: 100, l: 50 }); // { l: 0.63269, a: 0.23887, b: 0.08648 }
 hsl2oklab([344, 100, 50]); // { l: 0.63269, a: 0.23887, b: 0.08648 }
 ```
 
-**hsl2oklch(input: HSL | ColorTupple, precision?: number): string**  
+**hsl2oklch(input: HSL | ColorTuple, precision?: number): LCH**  
 Convert HSL to OKLCH.
 
 ```typescript
@@ -448,7 +351,7 @@ hsl2oklch({ h: 344, s: 100, l: 50 }); // { l: 0.63269, c: 0.25404, h: 19.90218 }
 hsl2oklch([344, 100, 50]); // { l: 0.63269, c: 0.25404, h: 19.90218 }
 ```
 
-**hsl2rgb(input: HSL | ColorTupple): RGB**  
+**hsl2rgb(input: HSL | ColorTuple): RGB**  
 Convert HSL to RGB.
 
 ```typescript
@@ -458,7 +361,7 @@ hsl2rgb({ h: 344, s: 100, l: 50 }); // { r: 255, g: 0, b: 68 }
 hsl2rgb([344, 100, 50]); // { r: 255, g: 0, b: 68 }
 ```
 
-**oklab2hex(input: LAB | ColorTupple): string**  
+**oklab2hex(input: LAB | ColorTuple): string**  
 Convert OKLAB to HEX.
 
 ```typescript
@@ -468,7 +371,7 @@ oklab2hex({ l: 0.63269, a: 0.23887, b: 0.08648 }); // '#ff0044'
 oklab2hex([0.63269, 0.23887, 0.08648]); // '#ff0044'
 ```
 
-**oklab2hsl(input: LAB | ColorTupple): HSL**  
+**oklab2hsl(input: LAB | ColorTuple): HSL**  
 Convert OKLAB to HSL.
 
 ```typescript
@@ -478,7 +381,7 @@ oklab2hsl({ l: 0.63269, a: 0.23887, b: 0.08648 }); // { h: 344, s: 100, l: 50 }
 oklab2hsl([0.63269, 0.23887, 0.08648]); // { h: 344, s: 100, l: 50 }
 ```
 
-**oklab2oklch(input: LAB | ColorTupple, precision?: number): LCH**  
+**oklab2oklch(input: LAB | ColorTuple, precision?: number): LCH**  
 Convert OKLAB to OKLCH.
 
 ```typescript
@@ -488,7 +391,7 @@ oklab2oklch({ l: 0.63269, a: 0.23887, b: 0.08648 }); // { l: 0.63269, c: 0.25404
 oklab2oklch([0.63269, 0.23887, 0.08648]); // { l: 0.63269, c: 0.25404, h: 19.90218 }
 ```
 
-**oklab2rgb(input: LAB | ColorTupple, precision: number = 0): RGB**  
+**oklab2rgb(input: LAB | ColorTuple, precision: number = 0): RGB**  
 Convert OKLAB to RGB.
 
 ```typescript
@@ -498,7 +401,7 @@ oklab2rgb({ l: 0.63269, a: 0.23887, b: 0.08648 }); // { r: 255, g: 0, b: 68 }
 oklab2rgb([0.63269, 0.23887, 0.08648]); // { r: 255, g: 0, b: 68 }
 ```
 
-**oklch2hex(input: LCH | ColorTupple): string**  
+**oklch2hex(input: LCH | ColorTuple): string**  
 Convert OKLCH to HEX.
 
 ```typescript
@@ -508,7 +411,7 @@ oklch2hex({ l: 0.63269, c: 0.25404, h: 19.90218 }); // '#ff0044'
 oklch2hex([0.63269, 0.25404, 19.90218]); // '#ff0044'
 ```
 
-**oklch2hsl(input: LCH | ColorTupple): HSL**  
+**oklch2hsl(input: LCH | ColorTuple): HSL**  
 Convert OKLCH to HSL.
 
 ```typescript
@@ -518,7 +421,7 @@ oklch2hsl({ l: 0.63269, c: 0.25404, h: 19.90218 }); // { h: 344, s: 100, l: 50 }
 oklch2hsl([0.63269, 0.25404, 19.90218]); // { h: 344, s: 100, l: 50 }
 ```
 
-**oklch2oklab(input: LCH | ColorTupple, precision?: number): LAB**  
+**oklch2oklab(input: LCH | ColorTuple, precision?: number): LAB**  
 Convert OKLCH to OKLAB.
 
 ```typescript
@@ -528,7 +431,7 @@ oklch2oklab({ l: 0.63269, c: 0.25404, h: 19.90218 }); // { l: 0.63269, a: 0.2388
 oklch2oklab([0.63269, 0.25404, 19.90218]); // { l: 0.63269, a: 0.23887, b: 0.08648 }
 ```
 
-**oklch2rgb(input: LCH | ColorTupple, precision: number = 0): RGB**  
+**oklch2rgb(input: LCH | ColorTuple, precision: number = 0): RGB**  
 Convert OKLCH to RGB.
 
 ```typescript
@@ -538,7 +441,7 @@ oklch2rgb({ l: 0.63269, c: 0.25404, h: 19.90218 }); // { r: 255, g: 0, b: 68 }
 oklch2rgb([0.63269, 0.25404, 19.90218]); // { r: 255, g: 0, b: 68 }
 ```
 
-**rgb2hex(input: RGB | ColorTupple): string**  
+**rgb2hex(input: RGB | ColorTuple): string**  
 Convert RGB to HEX.
 
 ```typescript
@@ -548,7 +451,7 @@ rgb2hex({ r: 255, g: 0, b: 68 }); // '#ff0044'
 rgb2hex([255, 0, 68]); // '#ff0044'
 ```
 
-**rgb2hsl(input: RGB | ColorTupple): HSL**  
+**rgb2hsl(input: RGB | ColorTuple): HSL**  
 Convert RGB to HSL.
 
 ```typescript
@@ -558,7 +461,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 | ColorTupple, precision: number): LAB**  
+**rgb2oklab(input: RGB | ColorTuple, precision: number): LAB**  
 Convert RGB to OKLAB.
 
 ```typescript
@@ -568,7 +471,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 | ColorTupple, precision: number): LCH**  
+**rgb2oklch(input: RGB | ColorTuple, precision: number): LCH**  
 Convert RGB to OKLCH.
 
 ```typescript
@@ -578,6 +481,109 @@ rgb2oklch({ r: 255, g: 0, b: 68 }); // { l: 0.63269, c: 0.25404, h: 19.90218 }
 rgb2oklch([255, 0, 68]); // { l: 0.63269, c: 0.25404, h: 19.90218 }
 ```
 
+### Utilities
+
+**addAlphaToHex(input: string, alpha: number): string**  
+Add an alpha value to a hex string
+
+```typescript
+import { addAlphaToHex } from 'colorizr';
+
+addAlphaToHex('#ff0044', 0.9); // '#ff0044e6'
+addAlphaToHex('#ff0044cc', 0.9); // '#ff0044e6'
+```
+
+**convertAlphaToHex(input: number): string**  
+Convert an alpha value to a hex value.
+
+```typescript
+import { convertAlphaToHex } from 'colorizr';
+
+convertAlphaToHex(0.5); // '80'
+```
+
+**extractAlphaFromHex(input: string): number**  
+Extract the alpha value from a hex string
+
+```typescript
+import { extractAlphaFromHex } from 'colorizr';
+
+convertAlphaToHex('#ff004480'); // 0.5
+```
+
+**extractColorParts(input: string): ExtractColorPartsReturn**  
+Extract the color parts from a CSS color string.
+Hex colors are not supported.
+
+```typescript
+type ExtractColorPartsReturn = {
+  alpha?: number;
+  model: 'hsl' | 'oklab' | 'oklch' | 'rgb';
+} & Record<string, number>;
+
+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**  
+Get a css string from a color object.
+
+```typescript
+import { formatCSS } from 'colorizr';
+
+formatCSS({ h: 344, s: 100, l: 50 }, { format: 'rgb' }); // 'rgb(255, 0, 68)'
+formatCSS({ r: 255, g: 0, b: 68 }, { alpha: 0.5, format: 'hsl' }); // 'hsla(344, 100%, 50%, 0.5)'
+```
+
+**formatHex(input: string): string**  
+Format a short hex string of 3 (or 4) digits into 6 (or 8) digits.
+
+```typescript
+import { formatHex } from 'colorizr';
+
+formatHex('#07e'); // '#0077ee'
+formatHex('#f058'); // '#ff005588'
+```
+**parseCSS(input: string, format?: ColorType): string | HSL | RGB**  
+Parse a css string to hex, HSL, OKLAB, OKLCH, or RGB.  
+If the format isn't set, it will return the same format as the input.
+
+```typescript
+import { parseCSS } from 'colorizr';
+
+parseCSS('hsl(344 100% 50%)'); // { h: 344, l: 50, s: 100 }
+parseCSS('#ff0044', 'hsl'); // { h: 344, l: 50, s: 100 }
+```
+
+**random(type: ColorType = 'hex'): string**  
+Get a random color.
+
+```typescript
+import { random } from 'colorizr';
+
+random(); // '#b385e0'
+random('oklch') // oklab(86.876% -0.22518 0.1597)
+```
+
+**removeAlphaFromHex(input: string): string**  
+Remove the alpha value from a hex string
+
+```typescript
+import { removeAlphaFromHex } from 'colorizr';
+
+removeAlphaFromHex('#ff0044cc'); // '#ff0044'
+```
+
+**textColor(input: string): string**  
+Get a contrasting color (black or white) for the input color.
+
+```typescript
+import { textColor } from 'colorizr';
+
+textColor('#ff0044'); // #ffffff
+textColor('#fff800'); // #000000
+```
+
 ### Validators
 
 **isValidColor(input: any): boolean**  
@@ -703,44 +709,20 @@ Get the luminance (0-1).
 Get the opacity (0-1).
 
 **colorizr.css**  
-Get the css string of the same time as the input.
+Get the css string of the same type as the input.
 
 **colorizr.textColor**
 Get a contrasting color (black or white).
 
-#### Manipulation
-
-**colorizr.lighten(percentage: number)**  
-Get a lighter color.
-
-**colorizr.darken(percentage: number)**  
-Get a darker color.
-
-**colorizr.desaturate(percentage: number)**  
-Get a desaturated color.
-
-**colorizr.saturate(percentage: number)**  
-Get a saturated color.
-
-**colorizr.rotate(degrees: number)**  
-Get a color with a hue rotated.
-
-**colorizr.invert()**  
-Get the inverted color.
-
-**colorizr.transparentize(percentage: number)**  
-Get a faded color.
-
-#### Comparison
-
-**colorizr.compare(color: string)**  
-Returns an object with the analysis (check the compare format above)
-
-#### Fortmatting
+#### Methods
 
 **colorizr.format(type: ColorType, precision?: number)**  
 Returns the formatted color with the type
 
+...
+
+Also, all the [manipulators](#Manipulators) and [comparison](#Comparison) utilities.
+
 ## Credits / References
 
 [color.js](https://github.com/color-js/color.js)