@thi.ng/color 5.3.3 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/color",
-  "version": "5.3.3",
+  "version": "5.4.0",
   "description": "Array-based color types, CSS parsing, conversions, transformations, declarative theme generation, gradients, presets",
   "type": "module",
   "module": "./index.js",
@@ -32,23 +32,25 @@
     "doc:stats": "tools:module-stats",
     "pub": "yarn npm publish --access public",
     "test": "testament test",
+    "tool:limits": "tools:node-esm tools/limits.ts",
     "tool:maxchroma": "tools:node-esm tools/max-chroma.ts",
+    "tool:strategies": "tools:node-esm tools/strategies.ts",
     "tool:swatches": "tools:node-esm tools/index.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.2",
-    "@thi.ng/arrays": "^2.5.5",
-    "@thi.ng/binary": "^3.3.19",
+    "@thi.ng/api": "^8.7.3",
+    "@thi.ng/arrays": "^2.5.6",
+    "@thi.ng/binary": "^3.3.20",
     "@thi.ng/checks": "^3.3.9",
-    "@thi.ng/compare": "^2.1.25",
-    "@thi.ng/compose": "^2.1.27",
-    "@thi.ng/defmulti": "^2.1.30",
-    "@thi.ng/errors": "^2.2.11",
-    "@thi.ng/math": "^5.4.3",
-    "@thi.ng/random": "^3.3.25",
-    "@thi.ng/strings": "^3.4.0",
-    "@thi.ng/transducers": "^8.3.34",
-    "@thi.ng/vectors": "^7.6.4"
+    "@thi.ng/compare": "^2.1.26",
+    "@thi.ng/compose": "^2.1.28",
+    "@thi.ng/defmulti": "^2.1.31",
+    "@thi.ng/errors": "^2.2.12",
+    "@thi.ng/math": "^5.4.4",
+    "@thi.ng/random": "^3.3.26",
+    "@thi.ng/strings": "^3.4.1",
+    "@thi.ng/transducers": "^8.3.35",
+    "@thi.ng/vectors": "^7.6.5"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.2",
@@ -300,6 +302,9 @@
     "./mix": {
       "default": "./mix.js"
     },
+    "./oklab/oklab-css": {
+      "default": "./oklab/oklab-css.js"
+    },
     "./oklab/oklab-rgb": {
       "default": "./oklab/oklab-rgb.js"
     },
@@ -309,6 +314,18 @@
     "./oklab/oklab": {
       "default": "./oklab/oklab.js"
     },
+    "./oklch/oklab-oklch": {
+      "default": "./oklch/oklab-oklch.js"
+    },
+    "./oklch/oklch-css": {
+      "default": "./oklch/oklch-css.js"
+    },
+    "./oklch/oklch-oklab": {
+      "default": "./oklch/oklch-oklab.js"
+    },
+    "./oklch/oklch": {
+      "default": "./oklch/oklch.js"
+    },
     "./rgb/hue-rgb": {
       "default": "./rgb/hue-rgb.js"
     },
@@ -427,5 +444,5 @@
       "vectors"
     ]
   },
-  "gitHead": "060a3a69281094df70be0e4f326a0ac3bbc3dd1d\n"
+  "gitHead": "a2915dee637c1b8cd2e11a78a23bd035e4f750e7\n"
 }

package/rgb/rgb-oklab.js

@@ -1,9 +1,18 @@
 import { powN3 } from "@thi.ng/vectors/pown";
 import { OKLAB_M2 } from "../api/constants.js";
 import { __mulV33 } from "../internal/matrix-ops.js";
+/**
+ * @remarks
+ * Reference:
+ * - https://bottosson.github.io/posts/oklab/#converting-from-linear-srgb-to-oklab
+ *
+ * @internal
+ */
+// prettier-ignore
 const CONE_LMS = [
-    0.412165612, 0.211859107, 0.0883097947, 0.536275208, 0.6807189584,
-    0.2818474174, 0.0514575653, 0.107406579, 0.6302613616,
+    0.4122214708, 0.2119034982, 0.0883024619,
+    0.5363325363, 0.6806995451, 0.2817188376,
+    0.0514459929, 0.1073969566, 0.6299787005,
 ];
 /**
  * @remarks

package/rotate.d.ts

@@ -1,4 +1,37 @@
 import type { Color, TypedColor } from "./api.js";
+/**
+ * Color rotation. Rotates hue by given `theta` and writes result color into
+ * `out`.
+ *
+ * @remarks
+ * If `out` is null, the resulting will be written back into `src`.
+ *
+ * As with all hue-based color modes in this package, the hue is stored
+ * normalized (in [0..1] interval) and NOT as degrees. The same goes for the
+ * rotation angle `theta`.
+ *
+ * Only supported for hue based color modes:
+ *
+ * - hcy
+ * - hsi
+ * - hsl
+ * - hsv
+ * - lch
+ * - oklch
+ *
+ * @param out
+ * @param src
+ * @param theta
+ */
 export declare const rotate: import("@thi.ng/defmulti").MultiFn3<import("@thi.ng/vectors").Vec | null, TypedColor<any>, number, import("@thi.ng/vectors").Vec>;
+/**
+ * Syntax sugar for {@link rotate} with 180 degree rotation.
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ */
 export declare const complementary: (out: Color | null, src: TypedColor<any>) => import("@thi.ng/vectors").Vec;
 //# sourceMappingURL=rotate.d.ts.map

package/rotate.js

@@ -3,8 +3,41 @@ import { fract } from "@thi.ng/math/prec";
 import { setC4 } from "@thi.ng/vectors/setc";
 import { __dispatch1 } from "./internal/dispatch.js";
 import { __ensureAlpha } from "./internal/ensure.js";
-export const rotate = defmulti(__dispatch1, { hsv: "hsl", hsi: "hsl", hcy: "hsl" }, {
+/**
+ * Color rotation. Rotates hue by given `theta` and writes result color into
+ * `out`.
+ *
+ * @remarks
+ * If `out` is null, the resulting will be written back into `src`.
+ *
+ * As with all hue-based color modes in this package, the hue is stored
+ * normalized (in [0..1] interval) and NOT as degrees. The same goes for the
+ * rotation angle `theta`.
+ *
+ * Only supported for hue based color modes:
+ *
+ * - hcy
+ * - hsi
+ * - hsl
+ * - hsv
+ * - lch
+ * - oklch
+ *
+ * @param out
+ * @param src
+ * @param theta
+ */
+export const rotate = defmulti(__dispatch1, { hcy: "hsl", hsi: "hsl", hsv: "hsl", oklch: "lch" }, {
     hsl: (out, src, theta) => setC4(out || src, fract(src[0] + theta), src[1], src[2], __ensureAlpha(src[3])),
     lch: (out, src, theta) => setC4(out || src, src[0], src[1], fract(src[2] + theta), __ensureAlpha(src[3])),
 });
+/**
+ * Syntax sugar for {@link rotate} with 180 degree rotation.
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ */
 export const complementary = (out, src) => rotate(out, src, 0.5);

package/tint.d.ts

@@ -1,6 +1,53 @@
 import type { MultiFn3O } from "@thi.ng/defmulti";
 import type { Color, TypedColor } from "./api.js";
+/**
+ * Creates a tinted version of given `src` color and writes result into `out`.
+ * The color is interpolated towards given `target` grayscale level (default: 1
+ * aka white).
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * Only supported for the following color modes:
+ *
+ * - hcy
+ * - hsi
+ * - hsv
+ * - lch
+ * - oklch
+ *
+ * @param out
+ * @param src
+ * @param amount
+ * @param target
+ */
 export declare const tint: MultiFn3O<Color | null, TypedColor<any>, number, number, Color>;
+/**
+ * Version of {@link tint} with medium gray as target.
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ * @param n
+ */
 export declare const tone: (out: Color | null, src: TypedColor<any>, n: number) => import("@thi.ng/vectors").Vec;
+/**
+ * Version of {@link tint} with black as target.
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ * @param n
+ */
 export declare const shade: (out: Color | null, src: TypedColor<any>, n: number) => import("@thi.ng/vectors").Vec;
 //# sourceMappingURL=tint.d.ts.map

package/tint.js

@@ -3,9 +3,56 @@ import { mix } from "@thi.ng/math/mix";
 import { setC4 } from "@thi.ng/vectors";
 import { __dispatch1 } from "./internal/dispatch.js";
 import { __ensureAlpha } from "./internal/ensure.js";
-export const tint = defmulti(__dispatch1, { hcy: "hsv", hsi: "hsv", hsl: "hsv" }, {
+/**
+ * Creates a tinted version of given `src` color and writes result into `out`.
+ * The color is interpolated towards given `target` grayscale level (default: 1
+ * aka white).
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * Only supported for the following color modes:
+ *
+ * - hcy
+ * - hsi
+ * - hsv
+ * - lch
+ * - oklch
+ *
+ * @param out
+ * @param src
+ * @param amount
+ * @param target
+ */
+export const tint = defmulti(__dispatch1, { hcy: "hsv", hsi: "hsv", hsl: "hsv", oklch: "lch" }, {
     hsv: (out, src, n, l = 1) => setC4(out || src, src[0], src[1] * (1 - n), mix(src[2], l, n), __ensureAlpha(src[3])),
     lch: (out, src, n, l = 1) => setC4(out || src, mix(src[0], l, n), src[1] * (1 - n), src[2], __ensureAlpha(src[3])),
 });
+/**
+ * Version of {@link tint} with medium gray as target.
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ * @param n
+ */
 export const tone = (out, src, n) => tint(out, src, n, 0.5);
+/**
+ * Version of {@link tint} with black as target.
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ * @param n
+ */
 export const shade = (out, src, n) => tint(out, src, n, 0);