@thi.ng/color 5.7.66 → 5.8.0

package/README.md

@@ -21,6 +21,14 @@ For the Clojure version, please visit: [thi.ng/color-clj](https://thi.ng/color-c
     - [Color creation / conversion](#color-creation--conversion)
   - [Storage & memory mapping](#storage--memory-mapping)
   - [Color theme generation](#color-theme-generation)
+  - [Color theme strategies](#color-theme-strategies)
+    - [Analog colors](#analog-colors)
+    - [Split-analog colors](#split-analog-colors)
+    - [Complementary colors](#complementary-colors)
+    - [Split-complementary colors](#split-complementary-colors)
+    - [Monochrome colors](#monochrome-colors)
+    - [Triadic colors](#triadic-colors)
+    - [Tetradic colors](#tetradic-colors)
   - [Color sorting & distance](#color-sorting--distance)
     - [Sorting memory-mapped colors](#sorting-memory-mapped-colors)
   - [Gradients](#gradients)
@@ -372,6 +380,87 @@ writeFileSync("swatches-ex01.svg", serialize(doc));
 
 ![example result color swatches](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/color/swatches-ex01.svg)
 
+### Color theme strategies
+
+In addition to the above approaches to create color themes, the package also provides these more standard strategies to derive a color theme from a given base color:
+
+#### Analog colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/analogStrategy.html)
+
+```ts tangle:export/analog-strategy.ts
+import { analogStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(analogStrategy("#f90")));
+//
+```
+
+#### Split-analog colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/splitAnalogStrategy.html)
+
+```ts tangle:export/split-analog-strategy.ts
+import { splitAnalogStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(splitAnalogStrategy("#f90")));
+//
+```
+
+#### Complementary colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/complementaryStrategy.html)
+
+```ts tangle:export/complementary-strategy.ts
+import { complementaryStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(complementaryStrategy("#f90")));
+//
+```
+
+#### Split-complementary colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/splitComplementaryStrategy.html)
+
+```ts tangle:export/split-complementary-strategy.ts
+import { splitComplementaryStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(splitComplementaryStrategy("#f90")));
+//
+```
+
+#### Monochrome colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/monochromeStrategy.html)
+
+```ts tangle:export/monochrome-strategy.ts
+import { monochromeStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(monochromeStrategy("#f90")));
+//
+```
+
+#### Triadic colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/triadicStrategy.html)
+
+```ts tangle:export/triadic-strategy.ts
+import { triadicStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(triadicStrategy("#f90")));
+//
+```
+
+#### Tetradic colors
+
+[Documentation](https://docs.thi.ng/umbrella/color/functions/tetradicStrategy.html)
+
+```ts tangle:export/tetradic-strategy.ts
+import { tetradicStrategy, cssColors } from "@thi.ng/color";
+
+console.log(cssColors(tetradicStrategy("#f90")));
+//
+```
+
 ### Color sorting & distance
 
 The package provides several functions to compute full or channel-wise distances
@@ -693,7 +782,7 @@ For Node.js REPL:
 const color = await import("@thi.ng/color");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 15.84 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 15.80 KB
 
 ## Dependencies
 

package/css/css.d.ts

@@ -55,4 +55,12 @@ export declare const setDefaultCSSConversions: (fns: CSSConversions) => Partial<
  * @param cssTarget - CSS conversions
  */
 export declare const css: (src: Exclude<MaybeColor, IParsedColor>, cssTarget?: CSSConversions) => string;
+/**
+ * Convenience helper to convert an iterable of colors into an array of CSS
+ * strings (using {@link css}).
+ *
+ * @param colors
+ * @param cssTarget
+ */
+export declare const cssColors: (colors: Iterable<Exclude<MaybeColor, IParsedColor>>, cssTarget?: CSSConversions) => string[];
 //# sourceMappingURL=css.d.ts.map

package/css/css.js

@@ -1,3 +1,4 @@
+import { ensureArray } from "@thi.ng/arrays/ensure-array";
 import { isNumber } from "@thi.ng/checks/is-number";
 import { isString } from "@thi.ng/checks/is-string";
 import { convert } from "../convert.js";
@@ -42,9 +43,11 @@ const css = (src, cssTarget = CSS_DEFAULT) => {
     convert([], src, "rgb", src.mode)
   ) : srgbCss(src);
 };
+const cssColors = (colors, cssTarget = CSS_DEFAULT) => ensureArray(colors).map((x) => css(x, cssTarget));
 export {
   CSS_LEVEL3,
   CSS_LEVEL4,
   css,
+  cssColors,
   setDefaultCSSConversions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/color",
-	"version": "5.7.66",
+	"version": "5.8.0",
 	"description": "Array-based color types, CSS parsing, conversions, transformations, declarative theme generation, gradients, presets",
 	"type": "module",
 	"module": "./index.js",
@@ -43,19 +43,19 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.6",
-		"@thi.ng/arrays": "^2.13.15",
-		"@thi.ng/binary": "^3.4.64",
-		"@thi.ng/checks": "^3.7.22",
-		"@thi.ng/compare": "^2.4.32",
-		"@thi.ng/compose": "^3.0.43",
-		"@thi.ng/defmulti": "^3.0.82",
-		"@thi.ng/errors": "^2.5.46",
-		"@thi.ng/math": "^5.13.3",
-		"@thi.ng/random": "^4.1.31",
-		"@thi.ng/strings": "^3.9.26",
-		"@thi.ng/transducers": "^9.6.14",
-		"@thi.ng/vectors": "^8.6.10"
+		"@thi.ng/api": "^8.12.7",
+		"@thi.ng/arrays": "^2.13.16",
+		"@thi.ng/binary": "^3.4.65",
+		"@thi.ng/checks": "^3.7.23",
+		"@thi.ng/compare": "^2.4.33",
+		"@thi.ng/compose": "^3.0.44",
+		"@thi.ng/defmulti": "^3.0.83",
+		"@thi.ng/errors": "^2.5.47",
+		"@thi.ng/math": "^5.13.4",
+		"@thi.ng/random": "^4.1.32",
+		"@thi.ng/strings": "^3.9.27",
+		"@thi.ng/transducers": "^9.6.15",
+		"@thi.ng/vectors": "^8.6.11"
 	},
 	"devDependencies": {
 		"esbuild": "^0.25.11",
@@ -446,5 +446,5 @@
 			"vectors"
 		]
 	},
-	"gitHead": "136a5e5ef0b69e82329db00d806c3c4e8f1aa063\n"
+	"gitHead": "d977f819bcafdcb2b24c45f8d01a167fe29fc85a\n"
 }

package/strategies.d.ts

@@ -1,13 +1,15 @@
+import type { MaybeColor } from "./api.js";
 import { type LCH } from "./lch/lch.js";
 /**
- * Returns array of `src` color and its complementary color, possibly adjusted
- * via optional `deltaL` and `deltaC` args (offsets for L & C channels).
+ * Returns array of `src` color (converted to LCH) and its complementary color,
+ * possibly adjusted via optional `deltaL` and `deltaC` args (offsets for L & C
+ * channels).
  *
  * @param src -
  * @param deltaL -
  * @param deltaC -
  */
-export declare const complementaryStrategy: (src: LCH, deltaL?: number, deltaC?: number) => LCH[];
+export declare const complementaryStrategy: (src: MaybeColor, deltaL?: number, deltaC?: number) => LCH[];
 /**
  * Returns array of `src` color and 2 neighboring colors, each ±rotated by
  * normalized `theta` and possibly adjusted via optional `deltaL` and `deltaC`
@@ -18,7 +20,7 @@ export declare const complementaryStrategy: (src: LCH, deltaL?: number, deltaC?:
  * @param deltaL -
  * @param deltaC -
  */
-export declare const analogStrategy: (src: LCH, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
+export declare const analogStrategy: (src: MaybeColor, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
 /**
  * Similar to {@link splitComplementaryStrategy}. Returns array of `src` color,
  * its complementary color and 2 of that colors' neighbors, each ±rotated by
@@ -30,7 +32,7 @@ export declare const analogStrategy: (src: LCH, theta?: number, deltaL?: number,
  * @param deltaL -
  * @param deltaC -
  */
-export declare const splitAnalogStrategy: (src: LCH, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
+export declare const splitAnalogStrategy: (src: MaybeColor, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
 /**
  * Similar to {@link splitAnalogStrategy}. Returns array of `src` color and 2
  * neighbors of its complementary color, each ±rotated by normalized `theta`
@@ -42,7 +44,7 @@ export declare const splitAnalogStrategy: (src: LCH, theta?: number, deltaL?: nu
  * @param deltaL -
  * @param deltaC -
  */
-export declare const splitComplementaryStrategy: (src: LCH, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
+export declare const splitComplementaryStrategy: (src: MaybeColor, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
 /**
  * Returns array of 5 colors all sharing same hue and chromacity of given `src`
  * color, but with these luminance settings: 0.0, 0.25, 0.5, 0.75, 1.0. Chroma
@@ -51,7 +53,7 @@ export declare const splitComplementaryStrategy: (src: LCH, theta?: number, delt
  * @param src -
  * @param deltaC -
  */
-export declare const monochromeStrategy: (src: LCH, deltaC?: number) => LCH[];
+export declare const monochromeStrategy: (src: MaybeColor, deltaC?: number) => LCH[];
 /**
  * Version of {@link splitComplementaryStrategy} with an hardcoded `theta` of
  * 1/6 to produce 3 colors with hues uniformly distributed on the color wheel
@@ -62,7 +64,7 @@ export declare const monochromeStrategy: (src: LCH, deltaC?: number) => LCH[];
  * @param deltaL -
  * @param deltaC -
  */
-export declare const triadicStrategy: (src: LCH, deltaL?: number, deltaC?: number) => LCH[];
+export declare const triadicStrategy: (src: MaybeColor, deltaL?: number, deltaC?: number) => LCH[];
 /**
  * Returns array of `src` color and 3 other colors whose hues form a rectangle,
  * using `theta` to define the angular separation. The hues are at: `src`,
@@ -75,7 +77,7 @@ export declare const triadicStrategy: (src: LCH, deltaL?: number, deltaC?: numbe
  * @param deltaL -
  * @param deltaC -
  */
-export declare const tetradicStrategy: (src: LCH, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
+export declare const tetradicStrategy: (src: MaybeColor, theta?: number, deltaL?: number, deltaC?: number) => LCH[];
 /**
  * Version of {@link tetradicStrategy} with an hardcoded `theta` of 1/4 to
  * produce 4 colors with hues uniformly distributed on the color wheel (possibly
@@ -86,5 +88,5 @@ export declare const tetradicStrategy: (src: LCH, theta?: number, deltaL?: numbe
  * @param deltaL -
  * @param deltaC -
  */
-export declare const squareStrategy: (src: LCH, deltaL?: number, deltaC?: number) => LCH[];
+export declare const squareStrategy: (src: MaybeColor, deltaL?: number, deltaC?: number) => LCH[];
 //# sourceMappingURL=strategies.d.ts.map

package/strategies.js

@@ -1,29 +1,40 @@
-import { clamp, clamp01 } from "@thi.ng/math/interval";
 import { lch } from "./lch/lch.js";
 import { rotate } from "./rotate.js";
 const $ = (src, l = 0, c = 0) => {
-  src.l = clamp01(src.l + l);
-  src.c = clamp(src.c + c, 0, 1.312);
+  src.l += l;
+  src.c += c;
   return src;
 };
-const complementaryStrategy = (src, deltaL, deltaC) => [src, $(rotate(lch(), src, 0.5), deltaL, deltaC)];
-const analogStrategy = (src, theta = 1 / 12, deltaL, deltaC) => [
-  src,
-  $(rotate(lch(), src, -theta), deltaL, deltaC),
-  $(rotate(lch(), src, theta), deltaL, deltaC)
-];
-const splitAnalogStrategy = (src, theta = 1 / 12, deltaL, deltaC) => [
-  ...splitComplementaryStrategy(src, theta, deltaL, deltaC),
-  $(rotate(lch(), src, theta), deltaL, deltaC)
-];
-const splitComplementaryStrategy = (src, theta = 1 / 12, deltaL, deltaC) => [
-  src,
-  $(rotate(lch(), src, 0.5 - theta), deltaL, deltaC),
-  $(rotate(lch(), src, 0.5 + theta), deltaL, deltaC)
-];
+const complementaryStrategy = (src, deltaL, deltaC) => {
+  const $src = lch(src);
+  return [$src, $(rotate(lch(), $src, 0.5), deltaL, deltaC)];
+};
+const analogStrategy = (src, theta = 1 / 12, deltaL, deltaC) => {
+  const $src = lch(src);
+  return [
+    $src,
+    $(rotate(lch(), $src, -theta), deltaL, deltaC),
+    $(rotate(lch(), $src, theta), deltaL, deltaC)
+  ];
+};
+const splitAnalogStrategy = (src, theta = 1 / 12, deltaL, deltaC) => {
+  const $src = lch(src);
+  return [
+    ...splitComplementaryStrategy($src, theta, deltaL, deltaC),
+    $(rotate(lch(), $src, theta), deltaL, deltaC)
+  ];
+};
+const splitComplementaryStrategy = (src, theta = 1 / 12, deltaL, deltaC) => {
+  const $src = lch(src);
+  return [
+    $src,
+    $(rotate(lch(), $src, 0.5 - theta), deltaL, deltaC),
+    $(rotate(lch(), $src, 0.5 + theta), deltaL, deltaC)
+  ];
+};
 const monochromeStrategy = (src, deltaC = 0) => {
-  let [_, c, h, a] = src;
-  c = clamp(c + deltaC, 0, 1.312);
+  let [_, c, h, a] = lch(src);
+  c += deltaC;
   return [
     lch(0, c, h, a),
     lch(0.25, c, h, a),
@@ -33,12 +44,15 @@ const monochromeStrategy = (src, deltaC = 0) => {
   ];
 };
 const triadicStrategy = (src, deltaL, deltaC) => splitComplementaryStrategy(src, 1 / 6, deltaL, deltaC);
-const tetradicStrategy = (src, theta = 1 / 12, deltaL, deltaC) => [
-  src,
-  $(rotate(lch(), src, theta), deltaL, deltaC),
-  $(rotate(lch(), src, 0.5), deltaL, deltaC),
-  $(rotate(lch(), src, 0.5 + theta), deltaL, deltaC)
-];
+const tetradicStrategy = (src, theta = 1 / 12, deltaL, deltaC) => {
+  const $src = lch(src);
+  return [
+    $src,
+    $(rotate(lch(), $src, theta), deltaL, deltaC),
+    $(rotate(lch(), $src, 0.5), deltaL, deltaC),
+    $(rotate(lch(), $src, 0.5 + theta), deltaL, deltaC)
+  ];
+};
 const squareStrategy = (src, deltaL, deltaC) => tetradicStrategy(src, 0.25, deltaL, deltaC);
 export {
   analogStrategy,