v0.6.0 Alpha 1

[LeaVerou]

v0.6.0

⬇️ 10 million downloads! + Making Color.js sustainable

Color.js has now been downloaded over 10 million times on npm!

You may have noticed we removed ads from the Color.js website a while back.
While Carbon ads were the good kind of ads (relevant, not intrusive), it was not really worth it, they barely made enough to cover costs like the domain name etc.

Instead, we have started an Open Collective that you can fund directly.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.

Breaking changes

There is a number of breaking changes in this release, but they should only negatively affect some pretty specialized use cases.

null instead of NaN to represent none values

As announced in v0.5.0, we have now switched to using null instead of NaN to represent none values (naturally occurring when converting achromatic colors to certain color spaces).
Not only is null conceptually closer, but since CSS also now has a NaN value, this change allows us to represent it properly, using an actual NaN value.

NaN continues to be parsed (and becomes NaN in JS). Instead of being serialized to NaN (which is invalid in CSS), it is serialized to calc(NaN) which is a valid coordinate in CSS. For roundtripping to work properly, this also means we now parse calc(NaN) as well. Slippery slope? We’ll see. 😁

If you are working with any code that needs to handle Color instances/objects generically, without knowing which version of Color.js they come from, you can detect which value is being used and use that instead of a hardcoded null or NaN:

let noneCoord = new Color("rgb(none none none)").coords[0];
const NONE_VALUE = noneCoord?.valueOf() ?? noneCoord;

(by @LeaVerou in cdf6f0d, @facelessuser in #476, @MysteryBlokHed in #530)

Plain numbers instead of Number objects for coordinates

Previously, coordinates would be parsed into Number objects so they could retain metadata about their parsing. From this release onwards, they are plain number primitives, which results in both performance improvements, and improved DX.

Instead, parsing metadata is passed around as a separate object, and stored on Color instances under color.parseMeta. This happens automatically in the OOP API, but users need to explicitly opt-in when using the procedural API, since that is optimized for high performance use cases.

In addition, this metadata is now far more elaborate and can pretty much recreate the format parsed. Which brings us to…

Colors now reserialized in the format parsed

We heard you! This has been a longstanding pain point, and it is now fixed. If you’re parsing a hex color, it will be serialized back to a hex color. If you’re specifying your chroma in percentages, percentages you’ll get back. If for some reason, you’re parsing a legacy comma-separated color, lo and behold, you can modify it and get back a legacy comma-separated color without lifting a finger!

Caveats:

• This only happens automatically in the OOP API. The procedural API does not store parsing metadata by default as it’s optimized for speed, you need to pass a parseMeta object explicitly.
• You can always override this by passing format (or format: "default") for the color space default, which gives you the previous behavior.

Other big improvements

New color spaces

• 🆕 OKHSL and OKHSV by @facelessuser (Add Okhsl and Okhsv #469 Ensure Okhsl and Okhsv return undefined hues for achromatic colors #517)
• 🆕 OkLrab and OkLrCh by @facelessuser (Add OkLrab and OkLrCh #511)
• 🆕 Linear Rec2100 by @lloydk (Add color space for Linear Rec2100 #591)

More control over serialization

You can now specify a format from any color space in serialize()/color.toString() without having to convert the color to a different color space.

And colorSpace.findFormat()

Another big pain point was that the way Color.js did serialization made simple things easy (by having sensible defaults and a wide range of predefined formats) and complex things possible (by allowing entirely custom formats to be specified), but the in-between was not smooth at all: the moment you needed anything custom, the only way was to recreate a whole format.

Starting with this release, you can now specify a lot more granular options for serialization, without having to redefine a format:

• coords with an array of coord types (e.g. ["<percentage>", "<number>[0, 100]", "<angle>"]). Any undefined values will just get the default type, so you can even do things like [, "<percentage>", ] to e.g. make OKLCh chroma a percentage without having to respecify the default type of any other coord.
• alpha to control display and type of alpha:
  1. Force alpha to be added even when it’s 100%: alpha: true
  2. Prevent alpha from being added, even when < 100%: alpha: false
  3. Format alpha as a percentage: alpha: "<percentage>"
  4. Do both 1 and 3: alpha: {include: true, type: "<percentage>"}

Switching from TypeScript types to JSDoc

You may have noticed that our API docs had not been great in the past. This is because we were describing types in .d.ts files, but documentation was in JSDoc comments. However (the otherwise lovely) Typedoc expects a single source of truth for both, which would mean either having untyped API docs, or API docs with only types. It also meant that we had to maintain Color.js’s pretty extensive API in two places, which did not scale.

With this release we went all in on JSDoc, thanks to @MysteryBlokHed’s monumental effort in #540.

Other Color.js Initiatives

Color Elements

You may have noticed our three experimental custom elements in the past — or maybe not, as they were very experimental and thus not featured very prominently.

These have now been split into a separate project, and a separate domain: https://elements.colorjs.io and expanded into a library of 10 web components for building color-related apps (the first library of its kind to our knowledge).
They are still very experimental, but way more polished than their previous state, and there is heavy activity on the project.

If you were referencing these from their previous URL, there is a redirect in place, but do note their tag names and API has changed.

Color Apps

We have also moved our Color apps (which also serve as Color.js demos) into their own repo and domain: https://apps.colorjs.io

If you have links to these, there’s nothing to worry about: the old URL still works (it just redirects to the new one).

There is also a new app:

• Gamut mapping: Explores different gamut mapping algorithms (used in CSS WG research)
  • Gamut mapping gradients by @jamesnw ([apps/gamut-mapping] Add gradient tool view #471)

Color Palettes

Another experimental project under the Color.js umbrella is Color Palettes,
which aims to analyze designer-created color palettes in a variety of color spaces, as an attempt to understand how to generate them
and document what patterns are prominent.
You may (or may not) be surprised to find that they are not regular in any color space, not even perceptually uniform ones.

This project is still in its infancy (I would not even call it alpha), but we are excited about its potential.

Other changes

API

• deltas() functions for getting coordinate/alpha differences between two colors in any color space. (@LeaVerou in deltas() function, closes #437 #532)
• get()/set()/setAll() now support alpha as well (by @LeaVerou)
• Hate seeing numbers like 0.30000000000000004 ? Our default number formatting now attempts to limit IEEE 754 precision issues.
• New DeltaE method: OK2 (believed to be more perceptually uniform) (by @svgeesus in [deltaE] Try out suggested DeltaE OK2 #486)
• Longer and undefined/same hues now have parity with CSS spec (thanks @facelessuser in Make longer and undefined/same hues have parity with CSS spec #474)
• New colorSpace.isUnbounded property (by @lloydk in Add isUnbounded to ColorSpace type #503)
• Improved number parsing (by @facelessuser in Fix number parsing #508)
• parse() now clamps alpha as well, just like the Color constructor (by @LeaVerou)
• Functional API now also available with ESM exports (by @MysteryBlokHed in [build] Build color-fn with ESM exports #606)
• getAll() now supports an optional options parameter object with space and precision as possible keys (by @DmitrySharabin in [getAll] Support precision, closes #542 #548)

Performance

• Matrix transform performance improvements by @lloydk that make certain conversions 3x faster (Add specialized matrix transform for Vector3 and Matrix3x3 #585 Change remaining color spaces to use faster matrix multiplication #588)

Docs

• API docs that are actually up to date, using typedoc! You can find them in (by @LeaVerou with help from @MysteryBlokHed in [types] Add more module documentation #498 [docs] Point typedoc at .d.ts files instead of .js #497 [docs] Ignore errors in JS files for typedoc #549)
• Updated color space diagram in https://colorjs.io/docs/spaces which is now dynamically generated via https://d2lang.com/ (by @LeaVerou)
• Demonstrate JND with colours that are different (by @perey in Demonstrate JND with colours that are different #538)

Website

• Avoid style recalculation of all elements on each scroll event. It makes the experience of working with the website much smoother (by @Inwerpsel in Avoid style recalculation of all elements on each scroll event #592)

Bug fixes

• Object-oriented functions now work between different sources of Color.js (by @MysteryBlokHed in Replace instanceof checks to work across color.js sources #605)
• Fix serialization of negative percentages (by @lloydk in Fix serialization of negative percentages #554)
• Handle negative square roots in a sane manner for Rec. 2100 HLG (by @facelessuser in Handle negative square roots in a sane manner for Rec. 2100 HLG #575)
• Do not use HSL normalized saturation and hue for certain spaces (by @facelessuser in Do not use HSL normalized saturation and hue for certain spaces #582)
• Avoid mutating arguments passed to the Color constructor (by @MysteryBlokHed in Avoid mutating objects in Color constructor #603)
• Fix parsing 7-character hex colors (by @kleinfreund in Fix parsing 7 character hex colors successfully #616)
• Fix parsing of percentage values for color spaces with coords that have a range property with a minimum value less than 0 (e.g. acescc) (by @lloydk in Fix parsing coords that have a minimum range < 0 #619)

Improvements to types

• Fix types for setAll(), getAll(), toGamut(), deltas(), and add types for CSS color keywords (by @lloydk in Fix types for setAll() #520 Fix toGamut() types #544 Add type for keywords #545 Fix getAll() types #546 Fix return type for deltas function #598)
• Generate declarations from JS, remove module augmentation, and fix type errors in codebase (by @MysteryBlokHed in [types] Generate declarations from JS #564 [types] Remove module augmentation (v0.6) #567 [types] Fix type errors in codebase #574)
• Overload multiplyMatrices types (by @epsilonError in [types] overload multiplyMatrices types #580)

For contributors

• Document how to serve in development, and add --serve to watch:html (by @jamesnw in Document how to serve in development, and add --serve to watch:html. #467)
• Testsuite & test coverage improvements (by @lloydk in Port color modification tests #480 Update htest to 0.0.11 #481 Fix/skip failing conversion tests #482 Skip failing deltaE tests #483 Port hooks tests #484 Speed up hsluv tests #489 Move HSLuv and HPLuv tests to hsluv directory #490 Port contrast tests to new test format #500 Fix RGBColorSpace type tests #543 Fix failing constructor test #556 Fix types and type tests #565 Fix remaining type test failures #569, @epsilonError in Port Multiply matrices tests to new format #559, and @kleinfreund in Fix parsing 7 character hex colors successfully #616)

Full Changelog: v0.5.0...v0.6.0

New Contributors

• @tychota made their first contribution in Update gamut-mapping.md #550
• @sroucheray made their first contribution in Update README.md #570
• @perey made their first contribution in Demonstrate JND with colours that are different #538
• @epsilonError made their first contribution in [types] overload multiplyMatrices types #580
• @Inwerpsel made their first contribution in Avoid style recalculation of all elements on each scroll event #592

---

This discussion was created from the release v0.6.0 Alpha 1.