@d3plus/color 3.0.0-alpha.0

package/README.md

@@ -0,0 +1,130 @@
+# @d3plus/color
+  
+Color functions that extent the ability of d3-color.
+
+## Installing
+
+If using npm, `npm install @d3plus/color`. Otherwise, you can download the [latest release from GitHub](https://github.com/d3plus/d3plus/releases/latest) or load from a [CDN](https://cdn.jsdelivr.net/npm/@d3plus/color@3.0.0-alpha.0/+esm).
+
+```js
+import modules from "@d3plus/color";
+```
+
+In vanilla JavaScript, a `d3plus` global is exported from the pre-bundled version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@d3plus/color@3.0.0-alpha.0"></script>
+<script>
+  console.log(d3plus);
+</script>
+```
+
+## Examples
+
+Live examples can be found on [d3plus.org](https://d3plus.org/), which includes a collection of example visualizations using @d3plus/react.
+
+## API Reference
+
+##### 
+* [colorAdd](#colorAdd) - Adds two colors together.
+* [colorAssign](#colorAssign) - Assigns a color to a value using a predefined set of defaults.
+* [colorContrast](#colorContrast) - A set of default color values used when assigning colors based on data.
+* [colorLegible](#colorLegible) - Darkens a color so that it will appear legible on a white background.
+* [colorLighter](#colorLighter) - Similar to d3.color.brighter, except that this also reduces saturation so that colors don't appear neon.
+* [colorSubtract](#colorSubtract) - Subtracts one color from another.
+
+##### 
+* [colorDefaults](#colorDefaults) - A set of default color values used when assigning colors based on data.
+
+| Name | Default | Description |
+|---|---|---|
+| dark | "#555555" | Used in the [contrast](#contrast) function when the color given is very light. |
+| light | "#f7f7f7" | Used in the [contrast](#contrast) function when the color given is very dark. |
+| missing | "#cccccc" | Used in the [assign](#assign) function when the value passed is `null` or `undefined`. |
+| off | "#C44536" | Used in the [assign](#assign) function when the value passed is `false`. |
+| on | "#6A994E" | Used in the [assign](#assign) function when the value passed is `true`. |
+| scale | "#4281A4", "#F6AE2D", "#C44536", "#2A9D8F", "#6A994E", "#CEB54A", "#5E548E", "#C08497", "#99582A", "#8C8C99", "#1D3557", "#D08C60", "#6D2E46", "#8BB19C", "#52796F", "#5E60CE", "#985277", "#5C374C" | An ordinal scale used in the [assign](#assign) function for non-valid color strings and numbers. |
+
+---
+
+<a name="colorAdd"></a>
+#### d3plus.**colorAdd**(c1, c2, [o1], [o2]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/add.js#L3)
+
+Adds two colors together.
+
+
+This is a global function
+
+---
+
+<a name="colorAssign"></a>
+#### d3plus.**colorAssign**(c, [u]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/assign.js#L4)
+
+Assigns a color to a value using a predefined set of defaults.
+
+
+This is a global function
+
+---
+
+<a name="colorContrast"></a>
+#### d3plus.**colorContrast**(c, [u]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/contrast.js#L4)
+
+A set of default color values used when assigning colors based on data.
+
+
+This is a global function
+
+---
+
+<a name="colorLegible"></a>
+#### d3plus.**colorLegible**(c) [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/legible.js#L3)
+
+Darkens a color so that it will appear legible on a white background.
+
+
+This is a global function
+
+---
+
+<a name="colorLighter"></a>
+#### d3plus.**colorLighter**(c, [i]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/lighter.js#L3)
+
+Similar to d3.color.brighter, except that this also reduces saturation so that colors don't appear neon.
+
+
+This is a global function
+
+---
+
+<a name="colorSubtract"></a>
+#### d3plus.**colorSubtract**(c1, c2, [o1], [o2]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/subtract.js#L3)
+
+Subtracts one color from another.
+
+
+This is a global function
+
+---
+
+<a name="colorDefaults"></a>
+#### **colorDefaults** [<>](https://github.com/d3plus/d3plus/blob/main/packages/color/src/defaults.js#L3)
+
+A set of default color values used when assigning colors based on data.
+
+| Name | Default | Description |
+|---|---|---|
+| dark | "#555555" | Used in the [contrast](#contrast) function when the color given is very light. |
+| light | "#f7f7f7" | Used in the [contrast](#contrast) function when the color given is very dark. |
+| missing | "#cccccc" | Used in the [assign](#assign) function when the value passed is `null` or `undefined`. |
+| off | "#C44536" | Used in the [assign](#assign) function when the value passed is `false`. |
+| on | "#6A994E" | Used in the [assign](#assign) function when the value passed is `true`. |
+| scale | "#4281A4", "#F6AE2D", "#C44536", "#2A9D8F", "#6A994E", "#CEB54A", "#5E548E", "#C08497", "#99582A", "#8C8C99", "#1D3557", "#D08C60", "#6D2E46", "#8BB19C", "#52796F", "#5E60CE", "#985277", "#5C374C" | An ordinal scale used in the [assign](#assign) function for non-valid color strings and numbers. |
+
+
+This is a global namespace
+
+---
+
+
+###### <sub>Documentation generated on Thu, 13 Mar 2025 19:58:28 GMT</sub>

package/es/index.js

@@ -0,0 +1,7 @@
+export { default as colorAdd } from "./src/add.js";
+export { default as colorAssign } from "./src/assign.js";
+export { default as colorContrast } from "./src/contrast.js";
+export { default as colorDefaults } from "./src/defaults.js";
+export { default as colorLegible } from "./src/legible.js";
+export { default as colorLighter } from "./src/lighter.js";
+export { default as colorSubtract } from "./src/subtract.js";

package/es/src/add.js

@@ -0,0 +1,22 @@
+import { hsl } from "d3-color";
+/**
+    @function colorAdd
+    @desc Adds two colors together.
+    @param {String} c1 The first color, a valid CSS color string.
+    @param {String} c2 The second color, also a valid CSS color string.
+    @param {String} [o1 = 1] Value from 0 to 1 of the first color's opacity.
+    @param {String} [o2 = 1] Value from 0 to 1 of the first color's opacity.
+    @returns {String}
+*/ export default function(c1, c2) {
+    var o1 = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : 1, o2 = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : 1;
+    c1 = hsl(c1);
+    c2 = hsl(c2);
+    var d = Math.abs(c2.h * o2 - c1.h * o1);
+    if (d > 180) d -= 360;
+    var h = (Math.min(c1.h, c2.h) + d / 2) % 360;
+    var l = c1.l + (c2.l * o2 - c1.l * o1) / 2, s = c1.s + (c2.s * o2 - c1.s * o1) / 2;
+    // a = o1 + (o2 - o1) / 2;
+    if (h < 0) h += 360;
+    return hsl("hsl(".concat(h, ",").concat(s * 100, "%,").concat(l * 100, "%)")).toString();
+// return hsl(`hsl(${h},${s * 100}%,${l * 100}%,${a})`).toString();
+}

package/es/src/assign.js

@@ -0,0 +1,22 @@
+import { color } from "d3-color";
+import { getColor } from "./defaults.js";
+/**
+    @function colorAssign
+    @desc Assigns a color to a value using a predefined set of defaults.
+    @param {String} c A valid CSS color string.
+    @param {Object} [u = defaults] An object containing overrides of the default colors.
+    @returns {String}
+*/ export default function(c) {
+    var u = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    // If the value is null or undefined, set to grey.
+    if ([
+        null,
+        void 0
+    ].indexOf(c) >= 0) return getColor("missing", u);
+    else if (c === true) return getColor("on", u);
+    else if (c === false) return getColor("off", u);
+    var p = color(c);
+    // If the value is not a valid color string, use the color scale.
+    if (!p) return getColor("scale", u)(c);
+    return c.toString();
+}

package/es/src/contrast.js

@@ -0,0 +1,14 @@
+import { getColor } from "./defaults.js";
+import { rgb } from "d3-color";
+/**
+    @function colorContrast
+    @desc A set of default color values used when assigning colors based on data.
+    @param {String} c A valid CSS color string.
+    @param {Object} [u = defaults] An object containing overrides of the default colors.
+    @returns {String}
+*/ export default function(c) {
+    var u = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    c = rgb(c);
+    var yiq = (c.r * 299 + c.g * 587 + c.b * 114) / 1000;
+    return yiq >= 128 ? getColor("dark", u) : getColor("light", u);
+}

package/es/src/defaults.js

@@ -0,0 +1,49 @@
+import { scaleOrdinal } from "d3-scale";
+/**
+    @namespace {Object} colorDefaults
+    @desc A set of default color values used when assigning colors based on data.
+      *
+      * | Name | Default | Description |
+      * |---|---|---|
+      * | dark | "#555555" | Used in the [contrast](#contrast) function when the color given is very light. |
+      * | light | "#f7f7f7" | Used in the [contrast](#contrast) function when the color given is very dark. |
+      * | missing | "#cccccc" | Used in the [assign](#assign) function when the value passed is `null` or `undefined`. |
+      * | off | "#C44536" | Used in the [assign](#assign) function when the value passed is `false`. |
+      * | on | "#6A994E" | Used in the [assign](#assign) function when the value passed is `true`. |
+      * | scale | "#4281A4", "#F6AE2D", "#C44536", "#2A9D8F", "#6A994E", "#CEB54A", "#5E548E", "#C08497", "#99582A", "#8C8C99", "#1D3557", "#D08C60", "#6D2E46", "#8BB19C", "#52796F", "#5E60CE", "#985277", "#5C374C" | An ordinal scale used in the [assign](#assign) function for non-valid color strings and numbers. |
+*/ var defaults = {
+    dark: "#555555",
+    light: "#f7f7f7",
+    missing: "#cccccc",
+    off: "#C44536",
+    on: "#6A994E",
+    scale: scaleOrdinal().range([
+        "#4281A4",
+        "#F6AE2D",
+        "#C44536",
+        "#2A9D8F",
+        "#6A994E",
+        "#CEB54A",
+        "#5E548E",
+        "#C08497",
+        "#99582A",
+        "#8C8C99",
+        "#1D3557",
+        "#D08C60",
+        "#6D2E46",
+        "#8BB19C",
+        "#52796F",
+        "#5E60CE",
+        "#985277",
+        "#5C374C"
+    ])
+};
+/**
+    Returns a color based on a key, whether it is present in a user supplied object or in the default object.
+    @returns {String}
+    @private
+*/ export function getColor(k) {
+    var u = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    return k in u ? u[k] : k in defaults ? defaults[k] : defaults.missing;
+}
+export default defaults;

package/es/src/legible.js

@@ -0,0 +1,14 @@
+import { hsl } from "d3-color";
+/**
+    @function colorLegible
+    @desc Darkens a color so that it will appear legible on a white background.
+    @param {String} c A valid CSS color string.
+    @returns {String}
+*/ export default function(c) {
+    c = hsl(c);
+    if (c.l > 0.45) {
+        if (c.s > 0.8) c.s = 0.8;
+        c.l = 0.45;
+    }
+    return c.toString();
+}

package/es/src/lighter.js

@@ -0,0 +1,15 @@
+import { hsl } from "d3-color";
+/**
+    @function colorLighter
+    @desc Similar to d3.color.brighter, except that this also reduces saturation so that colors don't appear neon.
+    @param {String} c A valid CSS color string.
+    @param {String} [i = 0.5] A value from 0 to 1 dictating the strength of the function.
+    @returns {String}
+*/ export default function(c) {
+    var i = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 0.5;
+    c = hsl(c);
+    i *= 1 - c.l;
+    c.l += i;
+    c.s -= i;
+    return c.toString();
+}

package/es/src/subtract.js

@@ -0,0 +1,22 @@
+import { hsl } from "d3-color";
+/**
+    @function colorSubtract
+    @desc Subtracts one color from another.
+    @param {String} c1 The base color, a valid CSS color string.
+    @param {String} c2 The color to remove from the base color, also a valid CSS color string.
+    @param {String} [o1 = 1] Value from 0 to 1 of the first color's opacity.
+    @param {String} [o2 = 1] Value from 0 to 1 of the first color's opacity.
+    @returns {String}
+*/ export default function(c1, c2) {
+    var o1 = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : 1, o2 = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : 1;
+    c1 = hsl(c1);
+    c2 = hsl(c2);
+    var d = c2.h * o2 - c1.h * o1;
+    if (Math.abs(d) > 180) d -= 360;
+    var h = (c1.h - d) % 360;
+    var l = c1.l - (c2.l * o2 - c1.l * o1) / 2, s = c1.s - (c2.s * o2 - c1.s * o1) / 2;
+    // a = o1 - (o2 - o1) / 2;
+    if (h < 0) h += 360;
+    return hsl("hsl(".concat(h, ",").concat(s * 100, "%,").concat(l * 100, "%)")).toString();
+// return hsl(`hsl(${h},${s * 100}%,${l * 100}%,${a})`).toString();
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@d3plus/color",
+  "version": "3.0.0-alpha.0",
+  "description": "Color functions that extent the ability of d3-color.",
+  "license": "MIT",
+  "type": "module",
+  "exports": "./es/index.js",
+  "browser": "./umd/d3plus-color.full.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "files": [
+    "umd",
+    "es"
+  ],
+  "homepage": "https://d3plus.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d3plus/d3plus.git",
+    "directory": "packages/color"
+  },
+  "keywords": [
+    "export",
+    "d3",
+    "d3plus",
+    "data",
+    "visualization"
+  ],
+  "scripts": {
+    "build:esm": "node ../../scripts/build-esm.js",
+    "build:umd": "node ../../scripts/build-umd.js",
+    "dev": "node ../../scripts/dev.js",
+    "test": "eslint index.js src/**/*.js && eslint --global=it test && mocha 'test/**/*-test.js'"
+  },
+  "dependencies": {
+    "d3-color": "^3.1.0",
+    "d3-scale": "^4.0.2"
+  }
+}