Docs

Fixes and new docs for tree-shakeable API

README.md

@@ -23,6 +23,7 @@ all with sensible defaults
 - **Up to date with CSS Color 4**: Every <a href="https://drafts.csswg.org/css-color-4/">CSS Color 4</a> format & color space supported for both <a href="docs/the-color-object.html">input</a> and <a href="https://colorjs.io/docs/output.html">output</a>, whether your browser supports it or not.
 - **Readable, object-oriented API**: Color objects for multiple operations on the same color, and static `Color.something()` functions for one-off calculations
 - **Modular & Extensible**: Use only what you need, or a bundle. Client-side or Node. Deep extensibility with <a href="https://colorjs.io/api/#Hooks-hooks.js">hooks</a>. </p>
+- **Fast & efficient**: <a href="https://colorjs.io/docs/procedural.html">Procedural, tree-shakeable API</a> available for performance sensitive tasks and reduced bundle size
 
 </header>
 

_includes/home.njk

@@ -43,6 +43,10 @@ includes: '<link rel="stylesheet" href="./assets/css/home.css">'
 			<h4>Modular & Extensible</h3>
 			<p>Use only what you need, or a bundle. Client-side or Node. Deep extensibility with <a href="api/#Hooks-hooks.js">hooks</a>. </p>
 		</article>
+		<article>
+			<h4>Fast & efficient</h3>
+			<p><a href="docs/procedural.html">Procedural, tree-shakeable API</a> available for performance sensitive tasks and reduced bundle size</p>
+		</article>
 	</div>
 </header>
 

benchmarks/ai.html

@@ -68,9 +68,10 @@
 import Color from "../src/color.js";
 import srgb from "../src/spaces/srgb.js";
 import oklch from "../src/spaces/oklch.js";
-import to from "../src/to.js";
-import inGamut from "../src/inGamut.js";
-import serialize from "../src/serialize.js";
+// import to from "../src/to.js";
+// import inGamut from "../src/inGamut.js";
+// import serialize from "../src/serialize.js";
+import {to, inGamut, serialize} from "../src/index-fn.js";
 
 test("Color.js", colorjs_canvas, {
 	create: (l, c, h) => ({space: oklch, coords: [l, c, h]}),
@@ -79,6 +80,13 @@
 	str: color_srgb => serialize(color_srgb)
 });
 
+// test("Color.js", colorjs_canvas, {
+// 	create: (l, c, h) => new Color(oklch, [l, c, h]),
+// 	to_srgb: color => color.to(srgb),
+// 	in: color_srgb => color_srgb.inGamut(srgb, {epsilon: 0}),
+// 	str: color_srgb => color_srgb.toString(color_srgb)
+// });
+
 
 import { displayable, rgb, formatRgb } from 'https://cdn.skypack.dev/culori';
 

docs/color-difference.md

@@ -62,32 +62,24 @@ another option is to use a better color model and perform a simpler color differ
 Examples include DeltaEJz (which uses JzCzhz) and deltaEITP (which uses ICtCp). An additional benefit of these two color difference formulae is that, unlike Lab which is mostly tested with medium to low chroma, reflective surface colors, JzCzhz and ICtCp are designed to be used with light-emitting devices (screens), high chroma colors often found in Wide Gamut content, and a much larger range of luminances as found in High Dynamic Range content.
 
 Color.js supports all the DeltaE algorithms mentioned above except DeltaE 94. Each DeltaE algorithm comes with its own method (e.g. `color1.deltaECMC(color2)`),
-as well as a parameterized syntax (e.g. `color1.deltaE(color2, "CMC")`) which falls back to DeltaE 76 when the requested algorithm is not available, or the second argument is missing.
-
-Note: If you are not using the Color.js bundle that includes everything, you will need to import the modules for DeltaE CMC, DeltaE 2000, DeltaEJz and DeltaEITP manually. DeltaE 76 is supported in the core Color.js.
+as well as a parameterized syntax (e.g. `color1.deltaE(color2, "CMC")`).
 
 ```js
-// These are not needed if you're just using the bundle
-// and will be omitted in other code examples
-import "https://colorjs.io/src/deltaE/deltaECMC.js";
-import "https://colorjs.io/src/deltaE/deltaE2000.js";
-import "https://colorjs.io/src/deltaE/deltaEITP.js";
-
 let color1 = new Color("blue");
 let color2 = new Color("lab", [30, 30, 30]);
 let color3 = new Color("lch", [40, 50, 60]);
 
 color1.deltaE(color2, "76");
-color2.deltaE(color3, "76");
+Color.deltaE(color2, color3, "76");
 
 color1.deltaE(color2, "CMC");
-color2.deltaE(color3, "CMC");
+Color.deltaE(color2, color3, "CMC");
 
 color1.deltaE(color2, "2000");
-color2.deltaE(color3, "2000");
+Color.deltaE(color2, color3, "2000");
 
 color1.deltaE(color2, "ITP");
-color2.deltaE(color3, "ITP");
+Color.deltaE(color2, color3, "ITP");
 ```
 
 For most DeltaE algorithms, 2.3 is considered the "Just Noticeable Difference" (JND).

docs/manipulation.md

@@ -2,25 +2,70 @@
 
 ## By color coordinates
 
-We've seen in the [previous section](the-color-object) how we can manipulate a color
+We've seen in a [previous section](the-color-object) how we can manipulate a color
 by directly manipulating coordinates in any of the color spaces supported.
-LCH coordinates are particularly useful for this so they are available directly on color objects:
+
+You can use properties to modify coordinates
+of any color space and convert back
+
+```js
+let color = new Color("slategray");
+color.lch.l = 80; // Set coord directly in any color space
+color.lch.c *= 1.2; // saturate by increasing LCH chroma by 20%
+color.hwb.w += 10; // any other color space also available
+```
+
+To modify coordinates in any color space you use `color.set()` and `color.setAll()`:
 
 ```js
-let color = new Color("rebeccapurple");
-color.l *= 1.2;
-color.c = 40;
-color.h += 30;
+let color = new Color("slategray");
+
+// Multiple coordinates
+color.set({
+	"lch.l": 80, // set lightness to 80
+	"lch.c": c => c * 1.2 // Relative manipulation
+});
+
+// Set single coordinate
+color.set("hwb.w", w => w + 10);
 ```
 
-You can also use `color.set()` to set multiple coordinates at once.
-In addition, it returns the color itself, so further methods can be called on it:
+Coordinates of the color's color space are available without a prefix:
 
+```js
+let color = new Color("slategray").to("lch");
+
+// Multiple coordinates
+color.set({
+	l: 80, // set lightness to 80
+	c: c => c * 1.2 // Relative manipulation
+});
+
+// Set single coordinate
+color.set("h", 30);
+```
+
+Chaining-style modifications are also supported:
 ```js
 let color = new Color("lch(50% 50 10)");
 color = color.set({
-	h: h => h + 180, // relative modification!
-	c: 60,
-	"hwb.w": w => w * 1.2
+	h: h => h + 180,
+	c: 60
 }).lighten();
 ```
+
+You can also use properties:
+
+```js
+let color = new Color("slategray");
+color.lch.l = 80; // Set coord directly in any color space
+color.lch.c *= 1.2; // saturate by increasing LCH chroma by 20%
+color.hwb.w += 10; // any other color space also available
+```
+
+Coordinates of the color's color space are available without a prefix:
+
+```js
+let color = new Color("slategray").to("lch");
+color.l = 80; // Set LCH lightness
+color.c *= 1.2; // saturate by increasing LCH chroma

docs/procedural.md

@@ -0,0 +1,51 @@
+---
+title: Procedural, tree-shakable API
+body_classes: cn-ignore language-javascript
+---
+
+# Procedural, tree-shakable API
+
+In addition to the object oriented API that most examples here use, Color.js also supports a procedural API
+that operates on plain objects instead of `Color` objects.
+
+There are several reasons to use this API:
+
+- It is approximately two times faster, making it more suitable for performance-sensitive tasks.
+- It is tree-shakeable (except color spaces at the moment), which results to a smaller bundle size when using build tools.
+- Personal preference: some people find procedural APIs easier to understand.
+
+To use it, you import functions from modules directly, either one by one or en masse.
+
+Note: These examples assume using [Color.js via npm](https://npmjs.com/package/colorjs.io)
+but everything applies to importing from URLs too.
+
+```js
+// Import multiple functions at once
+import {
+	to as convert,
+	toGamut,
+	serialize
+} from "colorjs.io/fn";
+
+// You can also import functions directly:
+import parse from "./node_modules/colorjs.io/src/parse.js";
+
+// Parsing color
+let red = parse("red");
+
+// Directly creating object literal
+let p3_lime = {space: "p3", coords: [0, 1, 0]};
+
+let p3_lime_srgb = convert(p3_green, "srgb");
+toGamut(p3_lime_srgb);
+serialize(p3_lime_srgb);
+```
+
+## More tips for performance-sensitive tasks
+
+In addition to using the procedural API for performance-sensitive tasks,
+here are a few more tips to make your code faster for those cases where every millisecond counts:
+
+- For any function that accepts a coord reference (such as `get(color, coord)` and `set(color, coord, value)`),
+provide it as an array or object (e.g. `[ColorSpace.get("lch"), "l"]` or `{space: ColorSpace.get("lch"), coordId: 'l'`)
+rather than a string that needs to be parsed (e.g. `"lch.l"`)

templates/_docs-nav.njk

@@ -6,3 +6,4 @@
 <li><a href="{{ page | relative }}/docs/interpolation.html">Interpolation</a></li>
 <li><a href="{{ page | relative }}/docs/adaptation.html">Chromatic Adaptation</a></li>
 <li><a href="{{ page | relative }}/docs/output.html">Output</a></li>
+<li><a href="{{ page | relative }}/docs/procedural.html">Procedural, tree-shakable API</a></li>