Merge branch 'opacity'

.eslintrc

@@ -4,9 +4,11 @@ ecmaFeatures:
 env:
     es6: true
     browser: true
+    node: true
 
 extends:
     "eslint:recommended"
 
 rules:
     no-cond-assign: 0
+    no-floating-decimal: 2

README.md

@@ -5,21 +5,28 @@ Even though your browser understands a lot about colors, it doesn’t offer much
 For example, take the color named “steelblue”:
 
 ```js
-var c = d3.color("steelblue"); // {r: 70, g: 130, b: 180}
+var c = d3.color("steelblue"); // {r: 70, g: 130, b: 180, opacity: 1}
 ```
 
 Let’s try converting it to HSL:
 
 ```js
-var c = d3.hsl("steelblue"); // {h: 207.27272727272728, s: 0.44, l: 0.4901960784313726}
+var c = d3.hsl("steelblue"); // {h: 207.27272727272728, s: 0.44, l: 0.4901960784313726, opacity: 1}
 ```
 
-Now rotate the hue by 90°, bump up the saturation, and format as hex:
+Now rotate the hue by 90°, bump up the saturation, and format as a string for CSS:
 
 ```js
 c.h += 90;
 c.s += 0.2;
-c + ""; // #c62dcd
+c + ""; // rgb(198, 45, 205)
+```
+
+To fade the color slightly:
+
+```js
+c.opacity = 0.8;
+c + ""; // rgba(198, 45, 205, 0.8)
 ```
 
 In addition to the ubiquitous and machine-friendly [RGB](#rgb) and [HSL](#hsl) color space, d3-color supports two color spaces that are designed for humans:
@@ -34,7 +41,7 @@ Cubehelix features monotonic lightness, while Lab and HCL are perceptually unifo
 If you use NPM, `npm install d3-color`. Otherwise, download the [latest release](https://github.com/d3/d3-color/releases/latest). The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom build using [Rollup](https://github.com/rollup/rollup) or your preferred bundler. You can also load directly from [d3js.org](https://d3js.org):
 
 ```html
-<script src="https://d3js.org/d3-color.v0.3.min.js"></script>
+<script src="https://d3js.org/d3-color.v0.4.min.js"></script>
 ```
 
 In a vanilla environment, a `d3_color` global is exported. [Try d3-color in your browser.](https://tonicdev.com/npm/d3-color)
@@ -45,16 +52,24 @@ In a vanilla environment, a `d3_color` global is exported. [Try d3-color in your
 
 Parses the specified [CSS Color Module Level 3](http://www.w3.org/TR/css3-color/#colorunits) *specifier* string, returning an [RGB](#rgb) or [HSL](#hsl) color. If the specifier was not valid, null is returned. Some examples:
 
-* `"rgb(255,255,255)"`
-* `"hsl(120,50%,20%)"`
-* `"#ffeeaa"`
-* `"#fea"`
-* `"steelblue"`
+* `rgb(255, 255, 255)`
+* `rgb(10%, 20%, 30%)`
+* `rgba(255, 255, 255, 0.4)`
+* `rgba(10%, 20%, 30%, 0.4)`
+* `hsl(120, 50%, 20%)`
+* `hsla(120, 50%, 20%, 0.4)`
+* `#ffeeaa`
+* `#fea`
+* `steelblue`
 
 The list of supported [named colors](http://www.w3.org/TR/SVG/types.html#ColorKeywords) is specified by CSS.
 
 Note: this function may also be used with `instanceof` to test if an object is a color instance. The same is true of color subclasses, allowing you to test whether a color is in a particular color space.
 
+<a name="color_opacity" href="#color_opacity">#</a> *color*.<b>opacity</b>
+
+This color’s opacity, typically in the range [0, 1].
+
 <a name="color_rgb" href="#color_rgb">#</a> *color*.<b>rgb</b>()
 
 Returns the [RGB equivalent](#rgb) of this color. For RGB colors, that’s `this`.
@@ -69,48 +84,48 @@ Returns a darker copy of this color. If *k* is specified, it controls how much b
 
 <a name="color_displayable" href="#color_displayable">#</a> *color*.<b>displayable</b>()
 
-Returns true if and only if the color is displayable on standard hardware. For example, this returns false for an RGB color if any channel value is less than zero or greater than 255.
+Returns true if and only if the color is displayable on standard hardware. For example, this returns false for an RGB color if any channel value is less than zero or greater than 255, or if the opacity is not in the range [0, 1].
 
 <a name="color_toString" href="#color_toString">#</a> *color*.<b>toString</b>()
 
-Returns the RGB hexadecimal string representing this color, such as `"#f7eaba"`. If this color is not displayable, a suitable displayable color is returned instead. For example, RGB channel values greater than 255 are clamped to 255.
+Returns a string representing this color according to the [CSS Object Model specification](https://drafts.csswg.org/cssom/#serialize-a-css-component-value), such as `rgb(247, 234, 186)`. If this color is not displayable, a suitable displayable color is returned instead. For example, RGB channel values greater than 255 are clamped to 255.
 
-<a name="rgb" href="#rgb">#</a> d3.<b>rgb</b>(<i>r</i>, <i>g</i>, <i>b</i>)<br>
+<a name="rgb" href="#rgb">#</a> d3.<b>rgb</b>(<i>r</i>, <i>g</i>, <i>b</i>[, <i>opacity</i>])<br>
 <a href="#rgb">#</a> d3.<b>rgb</b>(<i>specifier</i>)<br>
 <a href="#rgb">#</a> d3.<b>rgb</b>(<i>color</i>)<br>
 
 Constructs a new [RGB](https://en.wikipedia.org/wiki/RGB_color_model) color. The channel values are exposed as `r`, `g` and `b` properties on the returned instance. Use the [RGB color picker](http://bl.ocks.org/mbostock/78d64ca7ef013b4dcf8f) to explore this color space.
 
-If *r*, *g* and *b* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the RGB color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb). Note that unlike [*color*.rgb](#color_rgb) this method *always* returns a new instance, even if *color* is already an RGB color.
+If *r*, *g* and *b* are specified, these represent the channel values of the returned color; an *opacity* may also be specified. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the RGB color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb). Note that unlike [*color*.rgb](#color_rgb) this method *always* returns a new instance, even if *color* is already an RGB color.
 
-<a name="hsl" href="#hsl">#</a> d3.<b>hsl</b>(<i>h</i>, <i>s</i>, <i>l</i>)<br>
+<a name="hsl" href="#hsl">#</a> d3.<b>hsl</b>(<i>h</i>, <i>s</i>, <i>l</i>[, <i>opacity</i>])<br>
 <a href="#hsl">#</a> d3.<b>hsl</b>(<i>specifier</i>)<br>
 <a href="#hsl">#</a> d3.<b>hsl</b>(<i>color</i>)<br>
 
 Constructs a new [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) color. The channel values are exposed as `h`, `s` and `l` properties on the returned instance. Use the [HSL color picker](http://bl.ocks.org/mbostock/debaad4fcce9bcee14cf) to explore this color space.
 
-If *h*, *s* and *l* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the HSL color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to HSL. (Colors already in the HSL color space skip the conversion to RGB.)
+If *h*, *s* and *l* are specified, these represent the channel values of the returned color; an *opacity* may also be specified. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the HSL color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to HSL. (Colors already in the HSL color space skip the conversion to RGB.)
 
-<a name="lab" href="#lab">#</a> d3.<b>lab</b>(<i>l</i>, <i>a</i>, <i>b</i>)<br>
+<a name="lab" href="#lab">#</a> d3.<b>lab</b>(<i>l</i>, <i>a</i>, <i>b</i>[, <i>opacity</i>])<br>
 <a href="#lab">#</a> d3.<b>lab</b>(<i>specifier</i>)<br>
 <a href="#lab">#</a> d3.<b>lab</b>(<i>color</i>)<br>
 
 Constructs a new [Lab](https://en.wikipedia.org/wiki/Lab_color_space#CIELAB) color. The channel values are exposed as `l`, `a` and `b` properties on the returned instance. Use the [Lab color picker](http://bl.ocks.org/mbostock/9f37cc207c0cb166921b) to explore this color space.
 
-If *l*, *a* and *b* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the Lab color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to Lab. (Colors already in the Lab color space skip the conversion to RGB, and colors in the HCL color space are converted directly to Lab.)
+If *l*, *a* and *b* are specified, these represent the channel values of the returned color; an *opacity* may also be specified. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the Lab color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to Lab. (Colors already in the Lab color space skip the conversion to RGB, and colors in the HCL color space are converted directly to Lab.)
 
-<a name="hcl" href="#hcl">#</a> d3.<b>hcl</b>(<i>h</i>, <i>c</i>, <i>l</i>)<br>
+<a name="hcl" href="#hcl">#</a> d3.<b>hcl</b>(<i>h</i>, <i>c</i>, <i>l</i>[, <i>opacity</i>])<br>
 <a href="#hcl">#</a> d3.<b>hcl</b>(<i>specifier</i>)<br>
 <a href="#hcl">#</a> d3.<b>hcl</b>(<i>color</i>)<br>
 
 Constructs a new [HCL](https://en.wikipedia.org/wiki/Lab_color_space#CIELAB) color. The channel values are exposed as `h`, `c` and `l` properties on the returned instance. Use the [HCL color picker](http://bl.ocks.org/mbostock/3e115519a1b495e0bd95) to explore this color space.
 
-If *h*, *c* and *l* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the HCL color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to HCL. (Colors already in the HCL color space skip the conversion to RGB, and colors in the Lab color space are converted directly to HCL.)
+If *h*, *c* and *l* are specified, these represent the channel values of the returned color; an *opacity* may also be specified. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the HCL color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to HCL. (Colors already in the HCL color space skip the conversion to RGB, and colors in the Lab color space are converted directly to HCL.)
 
-<a name="cubehelix" href="#cubehelix">#</a> d3.<b>cubehelix</b>(<i>h</i>, <i>s</i>, <i>l</i>)<br>
+<a name="cubehelix" href="#cubehelix">#</a> d3.<b>cubehelix</b>(<i>h</i>, <i>s</i>, <i>l</i>[, <i>opacity</i>])<br>
 <a href="#cubehelix">#</a> d3.<b>cubehelix</b>(<i>specifier</i>)<br>
 <a href="#cubehelix">#</a> d3.<b>cubehelix</b>(<i>color</i>)<br>
 
 Constructs a new [Cubehelix](https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/) color. The channel values are exposed as `h`, `s` and `l` properties on the returned instance. Use the [Cubehelix color picker](http://bl.ocks.org/mbostock/ba8d75e45794c27168b5) to explore this color space.
 
-If *h*, *s* and *l* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the Cubehelix color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to Cubehelix. (Colors already in the Cubehelix color space skip the conversion to RGB.)
+If *h*, *s* and *l* are specified, these represent the channel values of the returned color; an *opacity* may also be specified. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the Cubehelix color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to Cubehelix. (Colors already in the Cubehelix color space skip the conversion to RGB.)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "d3-color",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Color spaces! RGB, HSL, Cubehelix, Lab and HCL (Lch).",
   "keywords": [
     "d3",
@@ -26,9 +26,9 @@
   },
   "scripts": {
     "pretest": "mkdir -p build && node -e 'process.stdout.write(\"var version = \\\"\" + require(\"./package.json\").version + \"\\\"; export * from \\\"../index\\\"; export {version};\");' > build/bundle.js && rollup -f umd -n d3_color -o build/d3-color.js -- build/bundle.js",
-    "test": "faucet `find test -name '*-test.js'` && eslint index.js src",
+    "test": "faucet `find test -name '*-test.js'` && eslint index.js src test",
     "prepublish": "npm run test && uglifyjs build/d3-color.js -c -m -o build/d3-color.min.js && rm -f build/d3-color.zip && zip -j build/d3-color.zip -- LICENSE README.md build/d3-color.js build/d3-color.min.js",
-    "postpublish": "VERSION=`node -e 'console.log(require(\"./package.json\").version)'`; git push && git tag -am \"Release $VERSION.\" v${VERSION} && git push --tags && cp build/d3-color.js ../d3.github.com/d3-color.v0.3.js && cp build/d3-color.min.js ../d3.github.com/d3-color.v0.3.min.js && cd ../d3.github.com && git add d3-color.v0.3.js d3-color.v0.3.min.js && git commit -m \"d3-color ${VERSION}\" && git push"
+    "postpublish": "VERSION=`node -e 'console.log(require(\"./package.json\").version)'`; git push && git tag -am \"Release $VERSION.\" v${VERSION} && git push --tags && cp build/d3-color.js ../d3.github.com/d3-color.v0.4.js && cp build/d3-color.min.js ../d3.github.com/d3-color.v0.4.min.js && cd ../d3.github.com && git add d3-color.v0.4.js d3-color.v0.4.min.js && git commit -m \"d3-color ${VERSION}\" && git push"
   },
   "devDependencies": {
     "faucet": "0.0",