@thi.ng/color 5.3.2 → 5.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-02-17T20:06:13Z
+- **Last updated**: 2023-03-02T18:09:03Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,44 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [5.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/color@5.4.0) (2023-03-02)
+
+#### 🚀 Features
+
+- add oklch mode impl/support ([3e77420](https://github.com/thi-ng/umbrella/commit/3e77420))
+  - add oklch() factory & class decl
+  - add oklab<>oklch conversions
+  - update analog() & rotate()
+- add CSS Level4 oklab/oklch support ([137d322](https://github.com/thi-ng/umbrella/commit/137d322))
+  - update parseCss() to support oklab/oklch colors
+  - add oklab/oklch CSS serializers
+  - update css() to optionally support CSS Color Module L4
+  - add CSS_LEVEL3 / CSS_LEVEL4 conversions
+- update color() to accept CSS color strings ([0d5b3e9](https://github.com/thi-ng/umbrella/commit/0d5b3e9))
+
+#### 🩹 Bug fixes
+
+- update oklab LMS matrices ([6e2cb75](https://github.com/thi-ng/umbrella/commit/6e2cb75))
+  - according to @bottosson they were already updated in 01/2021
+- update parseCss()/parseHex() ([dbbdc7d](https://github.com/thi-ng/umbrella/commit/dbbdc7d))
+  - fix support for percentages
+  - fix channel scale factors
+  - fix alpha-channel handling in parseHex()
+  - rename internal helpers
+  - add/update tests
+
+#### ⏱ Performance improvements
+
+- refactor distLch() ([fa2d4e0](https://github.com/thi-ng/umbrella/commit/fa2d4e0))
+  - use Law of Cosines impl to avoid 1x cos and 2x sin ops
+
+#### ♻️ Refactoring
+
+- update oklab/oklch channel ranges, add docs ([d87b30d](https://github.com/thi-ng/umbrella/commit/d87b30d))
+- update (ok)lab/lch CSS serializers ([8492f5e](https://github.com/thi-ng/umbrella/commit/8492f5e))
+  - extract internal helpers
+  - update/fix channel scale factors
+
 ## [5.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/color@5.3.0) (2023-02-10)
 
 #### 🚀 Features

package/README.md

@@ -60,28 +60,30 @@ from the integer types).
 - [Lab](https://en.wikipedia.org/wiki/CIELAB_color_space) (float4, D50/D65 versions)
 - [LCH](https://en.wikipedia.org/wiki/HCL_color_space) (float4)
 - [Oklab](https://bottosson.github.io/posts/oklab/) (float4)
+- [Oklch](https://bottosson.github.io/posts/oklab/) (float4) (polar version of oklab)
 - [RGB](https://en.wikipedia.org/wiki/RGB_color_space) (float4, _linear_)
 - [sRGB](https://en.wikipedia.org/wiki/SRGB) (float4, [gamma corrected](https://en.wikipedia.org/wiki/Gamma_correction))
 - [XYY](https://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space) (float4)
 - [XYZ](https://en.wikipedia.org/wiki/CIE_1931_color_space) (float4, aka CIE 1931, D50/D65 versions)
 - [YCC](https://en.wikipedia.org/wiki/YCbCr) (float4, aka YCbCr)
 
-| From/To   | CSS | HCY             | HSI             | HSL             | HSV             | Int             | Lab             | LCH | Oklab | RGB             | sRGB            | XYY | XYZ             | YCC             |
-|-----------|-----|-----------------|-----------------|-----------------|-----------------|-----------------|-----------------|-----|-------|-----------------|-----------------|-----|-----------------|-----------------|
-| **CSS**   | ✅   | 🆎              | 🆎              | ✅               | 🆎              | ✅<sup>(1)</sup> | ✅<sup>(4)</sup> | ✅   | 🆎    | ✅               | ✅               | 🆎  | 🆎              | 🆎              |
-| **HCY**   | 🆎  | ✅               | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
-| **HSI**   | 🆎  | 🆎              | ✅               | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
-| **HSL**   | ✅   | 🆎              | 🆎              | ✅               | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
-| **HSV**   | 🆎  | 🆎              | 🆎              | ✅               | ✅               | ❌               | 🆎              | 🆎  | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
-| **Int**   | ✅   | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎              | ✅               | ✅   | 🆎              | 🆎              |
-| **Lab**   | ✅   | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | ✅<sup>(3)</sup> | ✅   | 🆎    | ✅<sup>(3)</sup> | 🆎              | 🆎  | ✅<sup>(3)</sup> | 🆎              |
-| **LCH**   | ✅   | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | ✅               | ✅   | 🆎    | 🆎              | 🆎              | 🆎  | 🆎              | 🆎              |
-| **Oklab** | 🆎  | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | ✅     | ✅               | 🆎              | 🆎  | ✅               | 🆎              |
-| **RGB**   | 🆎  | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅               | ✅<sup>(3)</sup> | ✅   | ✅     | ✅               | ✅               | 🆎  | ✅<sup>(3)</sup> | ✅<sup>(2)</sup> |
-| **sRGB**  | ✅   | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅               | 🆎              | 🆎  | 🆎    | ✅               | ✅               | 🆎  | 🆎              | 🆎              |
-| **XYY**   | 🆎  | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎              | 🆎              | ✅   | ✅               | 🆎              |
-| **XYZ**   | 🆎  | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | ✅               | 🆎  | 🆎    | ✅               | 🆎              | ✅   | ✅<sup>(3)</sup> | 🆎              |
-| **YCC**   | 🆎  | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | ✅<sup>(2)</sup> | 🆎              | 🆎  | 🆎              | ✅               |
+| From/To   | CSS             | HCY             | HSI             | HSL             | HSV             | Int             | Lab             | LCH | Oklab | Oklch | RGB             | sRGB            | XYY | XYZ             | YCC             |
+|-----------|-----------------|-----------------|-----------------|-----------------|-----------------|-----------------|-----------------|-----|-------|-------|-----------------|-----------------|-----|-----------------|-----------------|
+| **CSS**   | ✅               | 🆎              | 🆎              | ✅               | 🆎              | ✅<sup>(1)</sup> | ✅<sup>(4)</sup> | ✅   | ✅     | ✅     | ✅               | ✅               | 🆎  | 🆎              | 🆎              |
+| **HCY**   | 🆎              | ✅               | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
+| **HSI**   | 🆎              | 🆎              | ✅               | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
+| **HSL**   | ✅               | 🆎              | 🆎              | ✅               | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
+| **HSV**   | 🆎              | 🆎              | 🆎              | ✅               | ✅               | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | 🆎  | 🆎              | 🆎              |
+| **Int**   | ✅               | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | 🆎              | ✅               | ✅   | 🆎              | 🆎              |
+| **Lab**   | ✅<sup>(5)</sup> | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | ✅<sup>(3)</sup> | ✅   | 🆎    | 🆎    | ✅<sup>(3)</sup> | 🆎              | 🆎  | ✅<sup>(3)</sup> | 🆎              |
+| **LCH**   | ✅<sup>(5)</sup> | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | ✅               | ✅   | 🆎    | 🆎    | 🆎              | 🆎              | 🆎  | 🆎              | 🆎              |
+| **Oklab** | ✅<sup>(5)</sup> | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | ✅     | ✅     | ✅               | 🆎              | 🆎  | ✅               | 🆎              |
+| **Oklch** | ✅<sup>(5)</sup> | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | ✅     | ✅     | 🆎              | 🆎              | 🆎  | 🆎              | 🆎              |
+| **RGB**   | 🆎              | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅               | ✅<sup>(3)</sup> | ✅   | ✅     | 🆎    | ✅               | ✅               | 🆎  | ✅<sup>(3)</sup> | ✅<sup>(2)</sup> |
+| **sRGB**  | ✅               | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅<sup>(2)</sup> | ✅               | 🆎              | 🆎  | 🆎    | 🆎    | ✅               | ✅               | 🆎  | 🆎              | 🆎              |
+| **XYY**   | 🆎              | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | 🆎              | 🆎              | ✅   | ✅               | 🆎              |
+| **XYZ**   | 🆎              | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | ✅               | 🆎  | 🆎    | 🆎    | ✅               | 🆎              | ✅   | ✅<sup>(3)</sup> | 🆎              |
+| **YCC**   | 🆎              | 🆎              | 🆎              | 🆎              | 🆎              | ❌               | 🆎              | 🆎  | 🆎    | 🆎    | ✅<sup>(2)</sup> | 🆎              | 🆎  | 🆎              | ✅               |
 
 - ✅ - direct conversion
 - 🆎 - indirect conversion (mostly via RGB/sRGB)
@@ -90,6 +92,7 @@ from the integer types).
   (see [Wikipedia](https://en.wikipedia.org/wiki/HSL_and_HSV#cite_note-26))
 - (3) - including [D50/D65 illuminant](https://en.wikipedia.org/wiki/Illuminant_D65) options
 - (4) - parsed as Lab w/ D50 illuminant as per [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#lab-colors)
+- (5) - only if targeting CSS Color Module Level 4 or newer
 
 #### Color creation / conversion
 
@@ -98,9 +101,9 @@ from other models/spaces. These functions can take the following arguments:
 
 - CSS string
 - number (interpreted as packed ARGB int32)
-- array (used as is)
+- array of color channel values (used as is)
 - scalars (one per channel, alpha optional, always defaults to 1.0)
-- color instance (triggers conversion)
+- color instance (might trigger conversion if needed)
 
 Additionally, an optional target backing buffer, start index and stride can be
 given. See [next section](#storage--memory-mapping).
@@ -598,7 +601,7 @@ For Node.js REPL:
 const color = await import("@thi.ng/color");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 15.25 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 15.51 KB
 
 ## Dependencies
 

package/alpha.d.ts

@@ -1,4 +1,12 @@
 import type { Color, ReadonlyColor } from "./api.js";
 export declare const alpha: (src: ReadonlyColor) => number;
+/**
+ * Creates version of `src` color with modified `alpha` and writes result into
+ * `out` (or if null, back into `src`).
+ *
+ * @param out
+ * @param src
+ * @param alpha
+ */
 export declare const setAlpha: (out: Color | null, src: ReadonlyColor, alpha: number) => import("@thi.ng/vectors").Vec;
 //# sourceMappingURL=alpha.d.ts.map

package/alpha.js

@@ -1,3 +1,11 @@
 import { setC4 } from "@thi.ng/vectors/setc";
 export const alpha = (src) => src[3] !== undefined ? src[3] : 1;
+/**
+ * Creates version of `src` color with modified `alpha` and writes result into
+ * `out` (or if null, back into `src`).
+ *
+ * @param out
+ * @param src
+ * @param alpha
+ */
 export const setAlpha = (out, src, alpha) => setC4(out || src, src[0], src[1], src[2], alpha);

package/analog.d.ts

@@ -8,6 +8,10 @@ export declare const defAnalog: FnU3<Fn3<number, number, IRandom, number>, Fn4<C
  * provided
  * [`IRandom`](https://docs.thi.ng/umbrella/random/interfaces/IRandom.html)
  * PRNG.
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  */
 export declare const analog: import("@thi.ng/defmulti").MultiFn4<import("@thi.ng/vectors").Vec | null, TypedColor<any>, number, IRandom | undefined, import("@thi.ng/vectors").Vec>;
 /**

package/analog.js

@@ -28,8 +28,12 @@ const analogNUU = defAnalog(analogN, analogU, analogU);
  * provided
  * [`IRandom`](https://docs.thi.ng/umbrella/random/interfaces/IRandom.html)
  * PRNG.
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  */
-export const analog = defmulti(__dispatch1, {}, {
+export const analog = defmulti(__dispatch1, { oklab: "lab50", oklch: "lch" }, {
     hcy: analogHNN,
     hsi: analogHNN,
     hsl: analogHNN,

package/api.d.ts

@@ -4,8 +4,11 @@ import type { IVector, ReadonlyVec, Vec } from "@thi.ng/vectors";
 export type Color = Vec;
 export type ReadonlyColor = ReadonlyVec;
 export type MaybeColor = TypedColor<any> | IParsedColor | ReadonlyColor | string | number;
+/**
+ * Color manipulation function. If `out` is null, the `src` will be mutated.
+ */
 export type ColorOp = (out: Color | null, src: ReadonlyColor) => Color;
-export type ColorMode = "argb32" | "abgr32" | "hcy" | "hsi" | "hsl" | "hsv" | "lab50" | "lab65" | "lch" | "oklab" | "rgb" | "srgb" | "xyy" | "xyz50" | "xyz65" | "ycc";
+export type ColorMode = "argb32" | "abgr32" | "hcy" | "hsi" | "hsl" | "hsv" | "lab50" | "lab65" | "lch" | "oklab" | "oklch" | "rgb" | "srgb" | "xyy" | "xyz50" | "xyz65" | "ycc";
 /**
  * Hue names in radial order, e.g. used by {@link namedHueRgb}.
  */
@@ -28,7 +31,15 @@ export interface IColor {
 }
 export interface ChannelSpec {
     /**
-     * Acceptable value range for this channel. Used by {@link TypedColor.clamp}.
+     * Acceptable approximate value range for this color channel. Used by
+     * {@link TypedColor.clamp} and {@link TypedColor.randomize}. At current and
+     * for compatibility reasons, the "valid" ranges for each color channel are
+     * configured such that they combined only approximately cover the full sRGB
+     * gamut (even though some color modes have gamuts larger than that).
+     * However, due to only using individual per-channel/per-axis definitions
+     * for those value ranges, it's still possible for colors in those larger
+     * color spaces to be slightly outside that sRGB gamut. These are soft
+     * limits, for orientation only.
      *
      * @defaultValue [0,1]
      */

package/clamp.d.ts

@@ -1,8 +1,15 @@
 import type { Color, ReadonlyColor } from "./api.js";
 /**
- * Clamps all color channels to [0,1] interval and calls `ensureAlpha`
- * to ensure alpha channel is defined (if missing sets it to `alpha`,
- * default: 1).
+ * Clamps all color channels to [0,1] interval and calls `ensureAlpha` to ensure
+ * alpha channel is defined (if missing sets it to `alpha`, default: 1).
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * Note: The result of this function might be different than
+ * {@link TypedColor.clamp}. The latter is taking into account pre-configured
+ * channel value ranges (per color mode). See {@link ChannelSpec.range} for
+ * details.
  *
  * @param out - result
  * @param src - source color
@@ -13,6 +20,9 @@ export declare const clamp: (out: Color | null, src: ReadonlyColor, alpha?: numb
  * Similar to {@link clamp}, but calls `ensureHue` to fold (instead of
  * clamping) the hue into [0,1] interval.
  *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  * @param out - result
  * @param src - source color
  * @param alpha - alpha value

package/clamp.js

@@ -3,9 +3,16 @@ import { fract } from "@thi.ng/math/prec";
 import { setC4 } from "@thi.ng/vectors/setc";
 import { __ensureAlpha } from "./internal/ensure.js";
 /**
- * Clamps all color channels to [0,1] interval and calls `ensureAlpha`
- * to ensure alpha channel is defined (if missing sets it to `alpha`,
- * default: 1).
+ * Clamps all color channels to [0,1] interval and calls `ensureAlpha` to ensure
+ * alpha channel is defined (if missing sets it to `alpha`, default: 1).
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * Note: The result of this function might be different than
+ * {@link TypedColor.clamp}. The latter is taking into account pre-configured
+ * channel value ranges (per color mode). See {@link ChannelSpec.range} for
+ * details.
  *
  * @param out - result
  * @param src - source color
@@ -16,6 +23,9 @@ export const clamp = (out, src, alpha = 1) => setC4(out || src, clamp01(src[0]),
  * Similar to {@link clamp}, but calls `ensureHue` to fold (instead of
  * clamping) the hue into [0,1] interval.
  *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  * @param out - result
  * @param src - source color
  * @param alpha - alpha value

package/color.d.ts

@@ -1,4 +1,27 @@
 import type { Color, ColorMode, ParsedColor, TypedColor } from "./api.js";
+/**
+ * Takes an CSS color string or the result of {@link parseCss} or a
+ * {@link ColorMode} and raw buffer and returns a suitable typed color wrapper
+ * for it (potentially by first parsing the color).
+ *
+ * @example
+ * ```ts
+ * color("springgreen");
+ * // $Color [srgb] { offset: 0, stride: 1, buf: [ 0, 1, 0.498, 1 ] }
+ *
+ * color("#ff0")
+ * // $Color [srgb] { offset: 0, stride: 1, buf: [ 1, 1, 0, 1 ] }
+ *
+ * color("oklch(60% 0.15 50)");
+ * // $Color [oklch] { offset: 0, stride: 1, buf: [ 0.6, 0.0015, 0.139, 1 ] }
+ *
+ * color("hsv", [0.5, 1, 1, 1])
+ * // $Color [hsv] { offset: 0, stride: 1, buf: [ 0.5, 1, 1, 1 ] }
+ * ```
+ *
+ * @param src
+ */
+export declare function color(src: string): TypedColor<any>;
 export declare function color(src: ParsedColor, buf?: Color, idx?: number, stride?: number): TypedColor<any>;
 export declare function color(mode: ColorMode, buf: Color, idx?: number, stride?: number): TypedColor<any>;
 //# sourceMappingURL=color.d.ts.map

package/color.js

@@ -1,4 +1,5 @@
 import { isString } from "@thi.ng/checks/is-string";
+import { parseCss } from "./css/parse-css.js";
 import { hcy } from "./hcy/hcy.js";
 import { hsi } from "./hsi/hsi.js";
 import { hsl } from "./hsl/hsl.js";
@@ -8,6 +9,7 @@ import { labD50 } from "./lab/lab50.js";
 import { labD65 } from "./lab/lab65.js";
 import { lch } from "./lch/lch.js";
 import { oklab } from "./oklab/oklab.js";
+import { oklch } from "./oklch/oklch.js";
 import { rgb } from "./rgb/rgb.js";
 import { srgb } from "./srgb/srgb.js";
 import { xyy } from "./xyy/xyy.js";
@@ -25,6 +27,7 @@ const FACTORIES = {
     lab65: labD65,
     lch,
     oklab,
+    oklch,
     rgb,
     srgb,
     xyy,
@@ -34,7 +37,9 @@ const FACTORIES = {
 };
 export function color(src, buf, idx, stride) {
     if (isString(src))
-        return FACTORIES[src](buf, idx, stride);
+        return buf
+            ? FACTORIES[src](buf, idx, stride)
+            : color(parseCss(src));
     if (buf) {
         const res = FACTORIES[src.mode](buf, idx, stride);
         res.set(src.deref());

package/convert.d.ts

@@ -9,5 +9,14 @@ export declare const CONVERSIONS: Partial<Record<ColorMode, Conversions>>;
  * @internal
  */
 export declare const defConversions: (mode: ColorMode, spec: ColorSpec<any, any>["from"]) => void;
+/**
+ * Converts a (raw, untyped) color from one mode to another and writes result
+ * into `out` (or if null, back into `src`).
+ *
+ * @param res
+ * @param src
+ * @param destMode
+ * @param srcMode
+ */
 export declare const convert: <T extends import("@thi.ng/vectors").Vec>(res: T | null, src: ReadonlyColor, destMode: ColorMode, srcMode: ColorMode) => T;
 //# sourceMappingURL=convert.d.ts.map

package/convert.js

@@ -25,6 +25,15 @@ export const defConversions = (mode, spec) => {
     }
     CONVERSIONS[mode] = { ...CONVERSIONS[mode], ...spec };
 };
+/**
+ * Converts a (raw, untyped) color from one mode to another and writes result
+ * into `out` (or if null, back into `src`).
+ *
+ * @param res
+ * @param src
+ * @param destMode
+ * @param srcMode
+ */
 export const convert = (res, src, destMode, srcMode) => {
     const spec = CONVERSIONS[destMode];
     assert(!!spec, `no conversions available for ${destMode}`);

package/css/css.d.ts

@@ -1,14 +1,32 @@
-import type { IParsedColor, MaybeColor } from "../api.js";
+import type { Fn } from "@thi.ng/api";
+import type { ColorMode, IParsedColor, MaybeColor } from "../api.js";
+export type CSSConversions = Partial<Record<ColorMode, Fn<any, string>>>;
+export declare const CSS_LEVEL3: CSSConversions;
 /**
- * Takes a color in one of the following formats and tries to convert it
- * to a CSS string:
+ * Extended set of direct CSS conversions for use with CSS Color Module Level 4.
+ * Based on {@link CSS_LEVEL3}.
+ */
+export declare const CSS_LEVEL4: CSSConversions;
+/**
+ * Takes a color in one of the following formats and tries to convert it to a
+ * CSS string.
+ *
+ * @remarks
+ * The following input formats are supported:
  *
  * - any {@link TypedColor} instance
  * - raw sRGB(A) vector
  * - number (packed 0xaarrggbb int, MUST provide alpha channel)
  * - string (passthrough)
  *
+ * If CSS Color Module Level 4 support is desired, pass {@link CSS_LEVEL4} as
+ * 2nd argument.
+ *
+ * If no direct conversion route for a given source color mode exists, the color
+ * will be first converted to sRGB and serialized as such.
+ *
  * @param col - source color
+ * @param cssTarget - CSS conversions
  */
-export declare const css: (src: Exclude<MaybeColor, IParsedColor>) => string;
+export declare const css: (src: Exclude<MaybeColor, IParsedColor>, cssTarget?: CSSConversions) => string;
 //# sourceMappingURL=css.d.ts.map

package/css/css.js

@@ -5,22 +5,21 @@ import { hslCss } from "../hsl/hsl-css.js";
 import { hsvCss } from "../hsv/hsv-css.js";
 import { intArgb32Css } from "../int/int-css.js";
 import { intAbgr32Argb32 } from "../int/int-int.js";
+import { labCss } from "../lab/lab-css.js";
+import { labLabD65_50 } from "../lab/lab-lab.js";
 import { lchLab } from "../lab/lab-lch.js";
 import { labRgb, labRgbD65 } from "../lab/lab-rgb.js";
+import { lchCss } from "../lch/lch-css.js";
+import { oklabCss } from "../oklab/oklab-css.js";
+import { oklchCss } from "../oklch/oklch-css.js";
 import { rgbCss } from "../rgb/rgb-css.js";
 import { rgbSrgb } from "../rgb/rgb-srgb.js";
 import { srgbCss } from "../srgb/srgb-css.js";
-/** @internal */
-const CSS_CONVERSIONS = {
+export const CSS_LEVEL3 = {
     abgr32: (x) => intArgb32Css(intAbgr32Argb32(x[0])),
     argb32: (x) => intArgb32Css(x[0]),
     hsl: hslCss,
     hsv: hsvCss,
-    // TODO temporarily disabled until CSS L4 is officially supported in browsers
-    // currently serializing as sRGB CSS
-    // lab50: labCss,
-    // lab65: (x) => labCss(labLabD65_50([], x)),
-    // lch: lchCss,
     lab50: (src) => srgbCss(rgbSrgb(null, labRgb([], src))),
     lab65: (src) => srgbCss(rgbSrgb(null, labRgbD65([], src))),
     lch: (src) => srgbCss(rgbSrgb(null, labRgb(null, lchLab([], src)))),
@@ -28,25 +27,47 @@ const CSS_CONVERSIONS = {
     srgb: srgbCss,
 };
 /**
- * Takes a color in one of the following formats and tries to convert it
- * to a CSS string:
+ * Extended set of direct CSS conversions for use with CSS Color Module Level 4.
+ * Based on {@link CSS_LEVEL3}.
+ */
+export const CSS_LEVEL4 = {
+    ...CSS_LEVEL3,
+    lab50: labCss,
+    lab65: (x) => labCss(labLabD65_50([], x)),
+    lch: lchCss,
+    oklab: oklabCss,
+    oklch: oklchCss,
+};
+/**
+ * Takes a color in one of the following formats and tries to convert it to a
+ * CSS string.
+ *
+ * @remarks
+ * The following input formats are supported:
  *
  * - any {@link TypedColor} instance
  * - raw sRGB(A) vector
  * - number (packed 0xaarrggbb int, MUST provide alpha channel)
  * - string (passthrough)
  *
+ * If CSS Color Module Level 4 support is desired, pass {@link CSS_LEVEL4} as
+ * 2nd argument.
+ *
+ * If no direct conversion route for a given source color mode exists, the color
+ * will be first converted to sRGB and serialized as such.
+ *
  * @param col - source color
+ * @param cssTarget - CSS conversions
  */
-export const css = (src) => {
+export const css = (src, cssTarget = CSS_LEVEL3) => {
     let asCss;
     return isString(src)
         ? src
         : isNumber(src)
             ? intArgb32Css(src)
             : src.mode
-                ? (asCss = CSS_CONVERSIONS[src.mode])
+                ? (asCss = cssTarget[src.mode])
                     ? asCss(src)
-                    : CSS_CONVERSIONS.rgb(convert([], src, "rgb", src.mode))
+                    : cssTarget.rgb(convert([], src, "rgb", src.mode))
                 : srgbCss(src);
 };

package/css/parse-css.d.ts

@@ -19,11 +19,21 @@ import { IParsedColor } from "../api.js";
  * - `hsl(h,s%,l%)`
  * - `hsla(h,s%,l%,a)`
  * - `lab(l a b / alpha?)`
+ * - `lab(l% a% b% / alpha?)`
  * - `lch(l c h / alpha?)`
+ * - `lch(l% c% h / alpha?)`
+ * - `oklab(l a b / alpha?)`
+ * - `oklab(l% a% b% / alpha?)`
+ * - `oklch(l c h / alpha?)`
+ * - `oklch(l% c% h / alpha?)`
  *
  * Hue values can be given according to CSS Color L4 spec (raw, deg, rad, grad,
  * turn): https://www.w3.org/TR/css-color-4/#typedef-hue
  *
+ * For (ok)lab/(ok)lch color channel values given as percentages, the scale
+ * ranges defined in the spec are used:
+ * https://www.w3.org/TR/css-color-4/#specifying-lab-lch
+ *
  * If no alpha channel is given, it will default to 1.0 (fully opaque).
  *
  * Note that any named or system CSS colors, hex colors and any RGB colors will
@@ -36,5 +46,20 @@ import { IParsedColor } from "../api.js";
  * @param src -
  */
 export declare const parseCss: (src: string | IDeref<string>) => IParsedColor;
+/**
+ * Parses a CSS hex color string into an uint32. Throws an error if given string
+ * doesn't conform to any of the supported formats.
+ *
+ * @remarks
+ * Supports the following input formats (`#` always optional and each letter a
+ * hex digit):
+ *
+ * - `#rgb`
+ * - `#rgba`
+ * - `#rrggbb`
+ * - `#rrggbbaa`
+ *
+ * @param src
+ */
 export declare const parseHex: (src: string) => number;
 //# sourceMappingURL=parse-css.d.ts.map