https://github.com/bfontaine/pheasant.js
Easy colors manipulations.
https://github.com/bfontaine/pheasant.js
colors js library
Last synced: about 2 months ago
JSON representation
Easy colors manipulations.
- Host: GitHub
- URL: https://github.com/bfontaine/pheasant.js
- Owner: bfontaine
- License: mit
- Created: 2013-03-06T18:03:56.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2015-01-05T12:32:53.000Z (over 11 years ago)
- Last Synced: 2026-04-06T19:41:58.580Z (3 months ago)
- Topics: colors, js, library
- Language: JavaScript
- Homepage:
- Size: 440 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pheasant.js
[](https://travis-ci.org/bfontaine/Pheasant.js)
**Pheasant.js** makes colors manipulations easy.
## Install
### Server-side (Node)
```sh
npm install pheasant
```
Then use:
```js
var Pheasant = require( 'pheasant' );
```
### Client-side
Include the `build/pheasant.min.js` file in your page. There’s no dependency,
only 15ko of pure JavaScript (4.5ko gzip’d). Pheasant can also be used as an AMD
module.
## Usage
Pheasant exposes one object, `Pheasant`. It has the following methods:
### .parse
This function returns a `Pheasant.Color` object of the parsed string, or null if it
can’t be parsed (see the support table below for the supported formats).
```js
Pheasant.parse( 'red' ); // red
Pheasant.parse( '#0F0' ); // green
Pheasant.parse( '#0000FF' ); // blue
Pheasant.parse( 'rgb(128, 128, 128)' ); // gray
Pheasant.parse( 'rgb(10%, 10%, 10%, 0.3)' ); // transparent gray
Pheasant.parse( 'rgba(255, 192, 203, 0.5)' ); // transparent pink
Pheasant.parse( 'hsl(240, 100%, 50%)' ); // blue
Pheasant.parse( 'hsla(120, 100%, 25%, 1)' ); // green
```
### .convert
This function takes two arguments, the first is the string to parse and the second
is the identifier of the format to convert to.
```js
Pheasant.parse( 'pink' ).toString( 'rgba' ); // 'rgba(255,192,203,1)'
Pheasant.convert( 'pink', 'rgba' ); // 'rgba(255,192,203,1)'
```
### .guessFormat
This function takes one argument, a string, and return the first identifier
of its format, if it’s a supported one. It returns `null` if it can’t guess
the format.
```js
Pheasant.guessFormat( '#ccc' ); // 'hex3'
Pheasant.guessFormat( '#cccbbb' ); // 'hex6'
Pheasant.guessFormat( '#cccb' ); // null
```
### .range
This function takes an object as its argument, and return a range of colors. The
object must have the following properties:
- `from`: The color to start the range with. It can be a valid color string, or a
`Pheasant.Color` object.
- `to`: The color to end the range with. As `from`, it can be a valid color
string, or a `Pheasant.Color` object.
Additionally, the object can have the following optional properties:
- `length`: the length of the range (default to 100).
- `type`: the type of the range values. It must be one of the following:
- `'string'` (default): Each value is a string describing the color. If you
provide a `format` attribute, it’ll be used. If it’s not provided and if the
two colors (`from` and `to`) both are strings of the same format, this is
the one which will be used. If none of theses conditions are met, the
default format will be used.
- `'object'`: Each value is a `Pheasant.Color` object.
- `'rgb'`: Each value is an array of three numbers, the red, green and blue
channels.
- `'rgba'`: Same as `'rgb'`, but with the alpha channel.
- `format`: this attribute is used only if the `type` is not provided or is set
to `'string'`. It defines the format used for the colors strings.
This function returns an empty array if `from` and/or `to` are missing, and/or if the
length is lesser or equal to zero, and/or if the `type` attribute is not valid, and/or
the `format` attribute is not valid, and/or `from` (or `to`) is a string which
cannot be parsed. Some values in the range may be null if you choose the
`colorName` format, since some values don’t have a name (e.g. `rgba(1, 1, 1)`).
```js
// [ '#fff', '#fff', '#fff' ]
Pheasant.range({ from: '#fff', to: '#fff', length: 3 });
// ["#abc", "#89a", "#568", "#345", "#123"]
Pheasant.range({ from: '#ABC', to: '#123', length: 5 });
// ["#40bf40", "#3ca13c", "#378337", "#336633", "#2e482e", "#2a2a2a"]
Pheasant.range({
from: 'hsl(120, 50%, 50%)',
to: 'rgb(42, 42, 42)',
length: 6,
format: 'hex6'
});
```
## Color objects
You can create a `Color` object using the following constructor:
```js
var color = new Pheasant.Color( red, green, blue, alpha );
```
`alpha` is optional (default to 1), and `red`, `green` and `blue` should be
integers between 0 and 255.
`Color` objects has four attributes, `.red`, `.green`, `.blue` and `.alpha`.
They also have two convenient methods: `.getRGB()` and `.getRGBA()`, which
return an array of `.red`, `.green` and `.blue` properties, plus the `.alpha`
one for `.getRGBA()`.
```js
Pheasant.parse( 'navy' ).blue; // 128
```
### .toString
You can use the `.toString()` method to convert colors to the format you want.
Without argument, it convert the color to the default format (`#ABCDEF`). You
can specify the format you want as a string. See the format identifiers below.
```js
Pheasant.parse( 'red' ).toString(); // '#f00'
Pheasant.parse( '#00F' ).toString( 'colorName' ); // 'blue'
var c = Pheasant.parse( 'rgb(245, 245, 220)' );
c.toString( 'colorName' ); // 'beige'
c.toString( 'hsl' ); // 'hsl(60,56%,91%)'
```
Since it may be painful to write `Pheasant.parse( 'foo' ).toString( 'bar' )` for
a one-time conversion, Pheasant has a method for that: `.convert`.
### .getRGB
This method returns an array of red, green and blue values.
```js
Pheasant.parse( 'red' ).getRGB(); // [ 255, 0, 0 ]
```
### .getRGBA
This method returns an array of red, green, blue, and opacity values.
```js
Pheasant.parse( 'red' ).getRGBA(); // [ 255, 0, 0, 1 ]
Pheasant.parse( 'hsla(42,12%,99%,0.5)' ).getRGBA(); // [ 253, 253, 252, 0.5 ]
```
### .getHSL
This method returns the equivalent HSL values of the color (hue, saturation,
lightness).
```js
Pheasant.parse( 'red' ).getHSL(); // [ 0, 100, 50 ]
Pheasant.parse( '#ffe' ).getHSL(); // [ 60, 100, 97 ]
```
### .getHSV
This method returns the equivalent HSV values of the color (hue, saturation,
value). HSV is also called HSB (“value” being replaced by “brightness”), so
an alias method called `.getHSB` is also available (this is exactly the same).
```js
Pheasant.parse( 'green' ).getHSV(); // [ 120, 100, 50 ]
```
### .negative
This method returns a new object representing the negative of the current color.
It preserves the alpha channel.
```
var c1 = new Pheasant.color( 42, 42, 42 ),
c2 = c1.negative();
c2.getRGB(); // [ 213, 213, 213 ]
Pheasant.parse( 'white' ).negative().toString( 'colorName' ); // 'black'
```
### .brightness
This method returns the [brightness index][brightness] of the color. This is an
integer between 0 (dark) and 255 (white). It can be used to mesure the contrast
between two colors.
[brightness]: http://www.had2know.com/technology/color-contrast-calculator-web-design.html
```js
Pheasant.parse( '#fff' ).brightness(); // 255
Pheasant.parse( 'rgb(42, 10, 134)' ).brightness(); // 34
```
### .isDarkerThan
This method tests if the color is darker than another color. You can pass it a
`Color` object or a string.
```js
Pheasant.parse( '#fff' ).isDarkerThan( '#eee' ); // false
Pheasant.parse( 'red' ).isDarkerThan( '#FAFAFA' ); // true
```
### .isLighterThan
This method tests if the color is lighter than another color. You can pass it a
`Color` object or a string.
```js
Pheasant.parse( '#fff' ).isLighterThan( '#eee' ); // true
Pheasant.parse( 'red' ).isLighterThan( '#FAFAFA' ); // false
```
### .eq
This method tests the equality between this color and another. You can pass it a
`Color` object or a string.
```js
Pheasant.parse( '#000' ).eq( 'rgba( 0, 0, 0)' ); // true
```
### .brightnessContrast
This method returns the brightness contrast between the current color and
another. It’s an integer between 0 and 255.
```js
Pheasant.parse( 'blue' ).brightnessContrast( 'yellow' ) // true
Pheasant.parse( 'blue' ).brightnessContrast( 'darkblue' ); // false
```
### .hueContrast
This method returns the hue contrast between the current color and another. It’s
an integer between 0 and 765. For the best readability, the brightness contrast
between the text color and the background color should be higher than 125, and
the hue contrast higher than 500.
## Color Formats
### Built-in Support
All standard CSS/SVG colors formats are supported.
| Format | Parsing | Stringifying | Identifiers |
|-------------|:-------:|:------------:|---------------------------|
| #ABC | ✔ | ✔ | `hex3`, `hexa3` |
| #ABCDEF | ✔ | ✔ | `hex6`, `hexa4` |
| color names | ✔ | ✔ | `colorName`, `colourName` |
| hsl() | ✔ | ✔ | `hsl` |
| hsla() | ✔ | ✔ | `hsla` |
| rgb()\* | ✔ | ✔ | `rgb` |
| rgba()\* | ✔ | ✔ | `rgba` |
Format identifiers are case-insensitive.
(\*): The `rgb()` and `rgba()` formats also support percentages values, like
`rgb(20%, 10%, 45%)` and `rgba(35%, 0%, 100%, 0.2)`. If you want to force
percentages in the output, append `%` to each identifier: `rgb%` and `rgba%`.
### Setting the default output format
The default ouput format (for `toString`) is `hex6`. You can change it with
`Pheasant.setDefaultStringFormat()`:
```js
Pheasant.parse( 'lightgreen' ).toString(); // '#90ee90'
Pheasant.setDefaultStringFormat( 'rgb' );
Pheasant.parse( 'lightgreen' ).toString(); // 'rgb(144,238,144)'
```
### Adding a format
You can add a new format with `Pheasant.addFormat()`. This method takes one
argument, an object with the following properties:
- `name`: the identifier(s) of the format. Must be a string (one identifier) or
an array of strings (multiple identifiers).
- `parse`: a function which convert a string in your format to a color
object. It must return an object with the following, optional, properties:
- `red`: the red channel (integer between 0 and 255)
- `blue`: the blue channel (integer between 0 and 255)
- `green`: the green channel (integer between 0 and 255)
- `alpha`: the alpha channel (float between 0 and 1)
If it can’t parse the string, it must return `null`. If the returned value is
not null, it’ll be wrapped in a `Pheasant.Color` object.
- `stringify`: a function wich convert a `Pheasant.Color` object to a string of
your format. It must return null if it can’t stringify the color (e.g.:
there’s `NaN` values in it).
- `normalize`: Optional. If set to `false`, the parsed string won’t be
normalized before being passed to your `.parse` function (the normalizing
process force the string to lowercase and remove trailing spaces).
- `test`: Optional. If it’s a function, it’ll be used to test whether a string
is valid in this format or not. If it’s a regex, its `.test` method will be
used. This attribute is used by the `.guessFormat` function.
The object must provide the `parse` and/or `stringify` attributes, and must
provide the `name` attribute.
When a string is passed to `Pheasant.parse`, it tries to parse it with every
available format. If no format can parse it (i.e. they all return `null`), it
returns `null`.
The `Pheasant.addFormat()` method return either:
- `null` if your format has only one name and it’s already taken
- the name of your format if it’s available
- an array of strings if your format has multiple names. Only the available
names are returned
This means that if you try to register a new format with the identifier `hex3`
(already taken), it won’t be registered and the call will return `null`. If you
try with `HEX3`, that’s the same since format identifiers are case-insensitive.
If your format has two names, `hex3` and `hex_3`, it will only be bound to
`hex_3`, since `hex3` is not available.
If you want to clear all the available formats, use the `Pheasant.formats`
object:
```js
Pheasant.formats = {};
```
### Example
Say you want to add a custom color format, which represent colors like that:
`custom://`. It doesn’t support the alpha channel, and
blue/red/green values are integer between 0 and 255. Here is how you can add
this format:
```js
Pheasant.addFormat((function() {
// this regex match your format
var custom_re = /custom:(\d{1,3})\/(\d{1,3})\/(\d{1,3})/;
return {
name: 'custom', // the name
test: custom_re, // this is used to test if a string is valid in your format
parse: function( s ) {
// parse the string
custom_re.lastIndex = 0;
var brg = custom_re.exec( s );
return { blue: +brg[1], red: +brg[2], green: +brg[3] };
},
stringify: function( c ) {
// stringify a Color object
return 'custom:' + c.blue + '/' + c.red + '/' + c.green;
}
};
})());
```
You can now try your format:
```js
Pheasant.guessFormat( 'custom:42/18/255' ); // 'custom'
Pheasant.parse( 'custom:1/2/3' ).getRGB(); // [ 2, 3, 1 ]
Pheasant.convert( '#ABC', 'custom' ); // "custom:204/170/187"
```
## Tests
Clone this repo, and then run `make test-all`:
```sh
git clone https://github.com/bfontaine/Pheasant.js.git
cd Pheasant
make test-all
```
You have to install the dependencies if they’re not already installed:
```sh
npm -g install mocha chai uglify-js mocha-phantomjs
# install Node-JSCoverage
git clone https://github.com/visionmedia/node-jscoverage.git
cd node-jscoverage
./configure && make && make install
```
You also need [PhantomJS][phantomjs].
[phantomjs]: http://phantomjs.org/download.html
## License
See the LICENSE file (MIT).
## Changelog
Date format is DD/MM/YYYY.
### v0.2.2 (08/10/2013)
- `Color#brightness`, `Color#brightnessContrast`, `Color#hueContrast`
- `Color#isLighterThan` & `Color#isDarkerThan` fixed
- `Color#getHSL`, `Color#getHSV`, `Color#getHSB`
### v0.2.1 (10/09/2013)
- AMD support (#6)
- On Node, `Pheasant` is now returned as the module itself (i.e.
`require('pheasant')`, not `require('pheasant').Pheasant`), but the old method
is still supported for backward compatibility.
### v0.2.0 (12/03/2013)
- `Pheasant#range`
- `Color#isLighterThan`, `Color#isDarkerThan`, `Color#eq`
- Minified version added
- Better doc
### v0.1.1 (10/03/2013)
- `Color#negative` (#3)
- `test` optional attribute support added on `.addFormat` argument
- `Pheasant.guessFormat` added
### v0.1.0 (09/03/2013)
First version.