Updates to docs; make filter functions return original color space

danburzo · danburzo · commit 04d68ac3f0d3 · 2020-08-11T21:19:05.000+03:00
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
-![(culori logo)](./docs/img/culori.svg)
+![culori](./docs/img/culori.svg)
 
-culori is a color library for JavaScript that works across many color spaces to offer conversion, interpolation, color difference formulas, and blending functions.
+<a href="https://www.npmjs.org/package/culori"><img src="https://img.shields.io/npm/v/culori.svg?style=flat-square&labelColor=d84f4c&color=black" alt="npm version"></a> <a href="https://bundlephobia.com/result?p=culori"><img src="https://img.shields.io/bundlephobia/minzip/culori?style=flat-square&labelColor=d84f4c&color=black" alt="npm version"></a>
+
+culori is a color library for JavaScript that works across many color spaces to offer conversion, interpolation, color difference formulas, blending functions, and more.
 
 [**Read the documentation**](https://culorijs.org)
diff --git a/docs/_includes/layouts/default.html b/docs/_includes/layouts/default.html
@@ -2,6 +2,7 @@
 <html>
 	<head>
 		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width,initial-scale=1" />
 		<title>
 			{% if title %} {{ title }} &middot; culori {% else %} culori {%
 			endif %}
diff --git a/docs/_includes/partials/header.html b/docs/_includes/partials/header.html
@@ -1,7 +1,9 @@
 <header>
 	<div class="container">
 		<div class="logo">
-			<a href='{{"/" | url }}'>culori</a>
+			<a href='{{"/" | url }}'>
+				<img src='{{ "/img/culori.svg" | url }}' alt="culori" />
+			</a>
 			<span
 				>v{{ pkg.version }} alpha (<a
 					href="https://github.com/evercoder/culori/releases"
diff --git a/docs/api.md b/docs/api.md
@@ -684,26 +684,12 @@ nearestNamedColors('lch(50% 70 60)', 3);
 
 ## Blending
 
-Color blending works as defined in the W3C [Compositing and Blending Level 2](https://drafts.fxtf.org/compositing-2/) specification.
+Culori makes available the separable blend modes defined in the W3C [Compositing and Blending Level 2](https://drafts.fxtf.org/compositing-2/) specification.
 
 <a name="blend" href="#blend">#</a> culori.**blend**(_colors_, _type = 'normal'_, _mode = 'rgb'_) → _color_ &middot; [Source](https://github.com/evercoder/culori/blob/master/src/blend.js)
 
-Available blending modes:
-
--   `normal`
--   `multiply`
--   `screen`
--   `hard-light`
--   `overlay`
--   `darken`
--   `lighten`
--   `color-dodge`
--   `color-burn`
--   `soft-light`
--   `difference`
--   `exclusion`
-
-> **Note:** culori currently implements the _separable_ blend modes, that is the blend modes that work on each channel in the color space independently. _color_, _hue_, _saturation_, and _lightness_ modes are not yet available.
+A separable blend mode is a simple formula that gets applied to each channel in the color space independently. The available blend modes are `color-burn`, `color-dodge`, `darken`, `difference`, `exclusion`, `hard-light`, `lighten`, `multiply`, `normal`, `overlay`, `screen`
+, and `soft-light`. They are designed to work on RGB colors, so _mode_ is expected to be `rgb` or `lrgb`.
 
 An example of blending three colors:
 
@@ -723,6 +709,8 @@ culori.blend(['red', 'green'], function average(b, s) {
 });
 ```
 
+The non-separable blend modes — `color`, `hue`, `saturation`, and `lightness` — are not available. The effect which they mean to produce is better obtained with simple formulas on a cylindrical color space (e.g. HSL).
+
 ## Random colors
 
 <a name="random" href="#random">#</a> culori.**random**(_mode = 'rgb'_, _constraints = {}_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/random.js)
@@ -790,14 +778,26 @@ culori.wcagContrast('red', 'black');
 
 ## Filters
 
-### CSS filter effects
+Filters apply certain graphical effects to a color. Culori currently implements two sets of filter functions:
+
+### CSS Filter Effects
+
+These correspond to the filter effects defined in the W3C [Filter Effects Module Level 1](https://drafts.fxtf.org/filter-effects-1/) specification.
 
-Culori implements some of the filter effects defined by the W3C [Filter Effects Module Level 1](https://drafts.fxtf.org/filter-effects-1/). The _amount_ parameter is usually in the `[0, 1]` interval, but may go above `1` for some filters. The filters were designed for RGB colors, so the _mode_ parameter is expected to be `rgb` or `lrgb`.
+The _amount_ parameter is usually in the `[0, 1]` interval, but may go above `1` for some filters. The filters were designed for RGB colors, so the _mode_ parameter is expected to be `rgb` or `lrgb`.
+
+The resulting color is returned in the color space of the original color.
 
 <a name="filterBrightness" href="#filterBrightness">#</a> culori.**filterBrightness**(_amount = 1_, _mode = 'rgb'_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/filter.js)
 
 The [`brightness()`](https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/brightness) CSS filter. An _amount_ of `1` leaves the color unchanged. Smaller values darken the color (with `0` being fully black), while larger values brighten it.
 
+```js
+let brighten = culori.filterBrightness(2, 'lrgb');
+brighten('salmon');
+// ⇒ { mode: 'rgb', r: 1.32…, g: 0.68…, b: 0.61… }
+```
+
 <a name="filterContrast" href="#filterContrast">#</a> culori.**filterContrast**(_amount = 1_, _mode = 'rgb'_) &middot; [Source](https://github.com/evercoder/culori/blob/master/src/filter.js)
 
 The [`contrast()`](https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/contrast) filter. An _amount_ of `1` leaves the color unchanged. Smaller values decrease the contrast (with `0` being fully gray), while larger values increase it.
@@ -832,6 +832,8 @@ culori
 // ⇒ ["#751800", "#664200", "#576c00", "#1a3e82", "#0010ff"];
 ```
 
+Some of the effects may be obtained more straightforwardly with simple calculations in other color spaces. For example, [hue rotation](#filterHueRotate) can just as well be implemented as `color.h += angle` in a cylindrical color space such as HSL.
+
 ### Color vision deficiency (CVD) simulation
 
 Simulate how a color may be perceived by people with color vision deficiencies (CVD).
diff --git a/docs/css/main.css b/docs/css/main.css
@@ -147,9 +147,9 @@ body {
 	line-height: 1.6;
 	margin: 0;
 
-	--aside-bg: var(--lavender);
+	--aside-bg: var(--mintcream);
 	--listing-bg: var(--whitesmoke);
-	--link-color: var(--indigo);
+	--link-color: #d84f4c;
 
 	--ff-main: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial,
 		sans-serif, Apple Color Emoji, Segoe UI Emoji;
@@ -205,7 +205,7 @@ article img {
 
 header {
 	padding: 0.25em 0 0;
-	background: linear-gradient(to bottom, var(--aside-bg), white);
+	/*background: linear-gradient(to bottom, var(--aside-bg), white);*/
 }
 
 footer .container {
@@ -272,6 +272,12 @@ a {
 	color: var(--link-color);
 }
 
+a:hover,
+a:focus {
+	outline: 2px dotted black;
+	outline-offset: 2px;
+}
+
 pre,
 code,
 kbd,
@@ -280,6 +286,14 @@ samp {
 	font-family: var(--ff-code);
 }
 
+.btn-link {
+	background: var(--link-color);
+	color: white;
+	padding: 1ch 2ch;
+	text-decoration: none;
+	display: inline-block;
+}
+
 /* syntax highlighting */
 
 code[class*='language-'],
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -18,7 +18,7 @@ culori = require('culori@{{pkg.version}}');
 
 ## Install it as an npm package
 
-<a href="https://www.npmjs.org/package/culori"><img src="https://img.shields.io/npm/v/culori.svg?style=flat" alt="npm version"></a> <a href="https://bundlephobia.com/result?p=culori"><img src="https://badgen.net/bundlephobia/minzip/culori" alt="bundlephobia"></a>
+<a href="https://www.npmjs.org/package/culori"><img src="https://img.shields.io/npm/v/culori.svg?style=flat-square&labelColor=d84f4c&color=black" alt="npm version"></a> <a href="https://bundlephobia.com/result?p=culori"><img src="https://img.shields.io/bundlephobia/minzip/culori?style=flat-square&labelColor=d84f4c&color=black" alt="npm version"></a>
 
 culori is bundled as both UMD and ES [on npm](https://npmjs.com/package/culori). Install it using `npm` or `yarn`:
 
diff --git a/docs/img/culori.svg b/docs/img/culori.svg
@@ -1,5 +1,5 @@
 <svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="132.262px" height="30.383px" viewBox="0 0 132.262 30.383">
-<path fill="#ED1C24" d="M18.07,27.704c-0.04,0.16-0.16,0.32-0.32,0.44c-1.319,0.84-3.958,2.119-7.676,2.119
+<path fill="#d84f4c" d="M18.07,27.704c-0.04,0.16-0.16,0.32-0.32,0.44c-1.319,0.84-3.958,2.119-7.676,2.119
 	C4.238,30.263,0,26.865,0,20.668C0,13.432,5.717,8.915,12.033,8.915c3.638,0,6.356,1.239,8.075,2.639c0.12,0.12,0.2,0.28,0.16,0.48
 	l-0.88,4.837c-0.04,0.32-0.2,0.48-0.52,0.56l-1.839,0.48c-0.28,0.08-0.44-0.04-0.52-0.24c-0.64-1.759-2.319-2.758-4.717-2.758
 	s-5.117,1.719-5.117,5.077c0,2.239,1.799,4.118,4.437,4.118c2.359,0,4.198-1.119,5.357-2.639c0.16-0.24,0.36-0.32,0.6-0.24
diff --git a/docs/index.md b/docs/index.md
@@ -4,10 +4,12 @@ layout: layouts/default
 menu-order: 0
 ---
 
-Culori is a color library for JavaScript that supports most color spaces and formats defined in the [CSS Colors Level 4][css4-colors] spec ([named colors][css4-named-colors], [Hex colors](hex-colors) (3 to 8 digits), [RGB](rgb-colors), [HSL](hsl-colors), [HWB](hwb-colors), [Lab and LCh](lab-colors)), plus [additional color spaces](./color-spaces).
+Culori is a color library for JavaScript that supports most color spaces and formats defined in the [CSS Colors Level 4][css4-colors] spec ([named colors][css4-named-colors], [Hex colors](hex-colors) with 3 to 8 digits, [RGB](rgb-colors), [HSL](hsl-colors), [HWB](hwb-colors), [Lab and LCh](lab-colors)), plus [additional color spaces](./color-spaces).
 
 It handles [color differences](https://en.wikipedia.org/wiki/Color_difference), interpolation, gradients, blend modes [and more](./api).
 
+<a class='btn-link' href='./getting-started'>Get started</a>
+
 ## Another JS color library?
 
 Mike Bostock's [d3-color](https://github.com/d3/d3-color), and Gregor Aisch's [chroma.js](https://github.com/gka/chroma.js) are two excellent, robust libraries that provide most of what you need for working with colors on the web. The [Resources](./resources) section for even more libraries you can try.
diff --git a/src/filter.js b/src/filter.js
@@ -1,5 +1,6 @@
 import { mapper, mapTransferLinear } from './map';
 import converter from './converter';
+import prepare from './_prepare';
 import lerp from './util/lerp';
 import { getModeDefinition } from './modes';
 
@@ -96,14 +97,17 @@ const matrixHueRotate = degrees => {
 	];
 };
 
-const matrix = (values, mode) => {
+const matrix = (values, mode, preserve_mode = false) => {
 	let conv = converter(mode);
 	let channels = getModeDefinition(mode).channels;
 	return color => {
 		let c = conv(color);
+		if (!c) {
+			return undefined;
+		}
 		let res = { mode };
-		let ch,
-			count = channels.length;
+		let ch;
+		let count = channels.length;
 		for (let i = 0; i < values.length; i++) {
 			ch = channels[Math.floor(i / count)];
 			if (c[ch] === undefined) {
@@ -112,29 +116,39 @@ const matrix = (values, mode) => {
 			res[ch] =
 				(res[ch] || 0) + values[i] * (c[channels[i % count]] || 0);
 		}
-		return res;
+		if (!preserve_mode) {
+			return res;
+		}
+		let prep = prepare(color);
+		return prep && res.mode !== prep.mode ? converter(prep.mode)(res) : res;
 	};
 };
 
 const filterBrightness = (amt = 1, mode = 'rgb') => {
 	let a = minzero(amt);
-	return mapper(mapTransferLinear(a), mode);
+	return mapper(mapTransferLinear(a), mode, true);
 };
+
 const filterContrast = (amt = 1, mode = 'rgb') => {
 	let a = minzero(amt);
-	return mapper(mapTransferLinear(a, (1 - a) / 2), mode);
+	return mapper(mapTransferLinear(a, (1 - a) / 2), mode, true);
 };
-const filterSepia = (amt = 1, mode = 'rgb') => matrix(matrixSepia(amt), mode);
+const filterSepia = (amt = 1, mode = 'rgb') =>
+	matrix(matrixSepia(amt), mode, true);
 const filterSaturate = (amt = 1, mode = 'rgb') =>
-	matrix(matrixSaturate(amt), mode);
+	matrix(matrixSaturate(amt), mode, true);
 const filterGrayscale = (amt = 1, mode = 'rgb') =>
-	matrix(matrixGrayscale(amt), mode);
+	matrix(matrixGrayscale(amt), mode, true);
 const filterInvert = (amt = 1, mode = 'rgb') => {
 	let a = clamp(amt);
-	return mapper((v, ch) => (ch === 'alpha' ? v : lerp(a, 1 - a, v)), mode);
+	return mapper(
+		(v, ch) => (ch === 'alpha' ? v : lerp(a, 1 - a, v)),
+		mode,
+		true
+	);
 };
 const filterHueRotate = (deg = 0, mode = 'rgb') =>
-	matrix(matrixHueRotate(deg), mode);
+	matrix(matrixHueRotate(deg), mode, true);
 
 export {
 	filterBrightness,
diff --git a/src/map.js b/src/map.js
@@ -1,14 +1,14 @@
 import converter from './converter';
 import identity from './util/identity';
-import _prepare from './_prepare';
+import prepare from './_prepare';
 import { getModeDefinition } from './modes';
 
-const mapper = (fn, mode = 'rgb') => {
+const mapper = (fn, mode = 'rgb', preserve_mode = false) => {
 	let channels = mode ? getModeDefinition(mode).channels : null;
-	let conv = mode ? converter(mode) : _prepare;
+	let conv = mode ? converter(mode) : prepare;
 	return color => {
 		let conv_color = conv(color);
-		return (channels || getModeDefinition(color.mode).channels).reduce(
+		let res = (channels || getModeDefinition(color.mode).channels).reduce(
 			(res, ch) => {
 				let v = fn(conv_color[ch], ch, conv_color, mode);
 				if (v !== undefined && !isNaN(v)) {
@@ -18,6 +18,14 @@ const mapper = (fn, mode = 'rgb') => {
 			},
 			{ mode }
 		);
+		if (!preserve_mode) {
+			return res;
+		}
+		let prep = prepare(color);
+		if (prep && prep.mode !== res.mode) {
+			return converter(prep.mode)(res);
+		}
+		return res;
 	};
 };
 
diff --git a/test/filter.test.js b/test/filter.test.js
@@ -11,10 +11,25 @@ import {
 } from '../src/index';
 
 tape('filterBrightness', t => {
+	t.deepEqual(
+		filterBrightness(1)('hsl(60 100% 50% / 25%)'),
+		{ mode: 'hsl', h: 60, s: 1, l: 0.5, alpha: 0.25 },
+		'unchanged in the original color space'
+	);
+	t.equal(
+		formatHex(filterBrightness(2)('#003366')),
+		'#0066cc',
+		'brightens the color'
+	);
 	t.end();
 });
 
 tape('filterContrast', t => {
+	t.equal(
+		formatHex(filterContrast(2)('#003366')),
+		'#00004d',
+		'Increases the contrast'
+	);
 	t.end();
 });
 
