add functionality to create color hashes for text inputs based on the configured palette

Author: haschek

src/common/index.ts

@@ -1,6 +1,7 @@
 import { invisibleZeroWidthCharacters } from "./utils/characters";
 import { colorCalculateDistance } from "./utils/colorCalculateDistance";
 import decideContrastColorValue from "./utils/colorDecideContrastvalue";
+import { getEnabledColorsFromPalette, textToColorHash } from "./utils/colorHash";
 import getColorConfiguration from "./utils/getColorConfiguration";
 import { getScrollParent } from "./utils/getScrollParent";
 import { getGlobalVar, setGlobalVar } from "./utils/globalVars";
@@ -15,4 +16,6 @@ export const utils = {
     getGlobalVar,
     setGlobalVar,
     getScrollParent,
+    getEnabledColorsFromPalette,
+    textToColorHash,
 };

src/common/utils/colorHash.ts

@@ -0,0 +1,197 @@
+import Color from "color";
+
+import { CLASSPREFIX as eccgui, COLORMINDISTANCE } from "../../configuration/constants";
+
+import { colorCalculateDistance } from "./colorCalculateDistance";
+import CssCustomProperties from "./CssCustomProperties";
+
+type ColorOrFalse = Color | false;
+
+interface getEnabledColorsProps {
+    /** Include "identity colors" from palette. */
+    includeIdentityColors?: boolean;
+    /** Include "semantic colors" (used for info, success, warning, danger) from palette. */
+    includeSemanticColors?: boolean;
+    /** Include "layout colors" from palette. */
+    includeLayoutColors?: boolean;
+    /** Include "extra colors" (e.g. gold, silver, bronze) from palette. */
+    includeExtraColors?: boolean;
+    /** Only keep colors in the stack with a minimal color distance to all other colors. */
+    minimalColorDistance?: number;
+    /** Extend color stack by values generated by mixing tints of the same weight, e.g. `yellow100` with `purple100`. */
+    // includeMixedColors?: boolean;
+}
+
+const getEnabledColorsFromPaletteCache = new Map<string, Color[]>();
+
+export function getEnabledColorsFromPalette({
+    includeIdentityColors = false,
+    includeSemanticColors = false,
+    includeLayoutColors = true,
+    includeExtraColors = false,
+    // TODO (planned for later): includeMixedColors = false,
+    minimalColorDistance = COLORMINDISTANCE,
+}: getEnabledColorsProps): Color[] {
+    const configId = JSON.stringify({
+        includeIdentityColors,
+        includeSemanticColors,
+        includeLayoutColors,
+        includeExtraColors,
+        minimalColorDistance,
+    });
+
+    if (getEnabledColorsFromPaletteCache.has(configId)) {
+        return getEnabledColorsFromPaletteCache.get(configId)!;
+    }
+
+    const colorsFromPalette = new CssCustomProperties({
+        selectorText: `:root`,
+        filterName: (name: string) => {
+            return (
+                (includeIdentityColors && name.includes(`--${eccgui}-color-palette-identity-`)) ||
+                (includeSemanticColors && name.includes(`--${eccgui}-color-palette-semantic-`)) ||
+                (includeLayoutColors && name.includes(`--${eccgui}-color-palette-layout-`)) ||
+                (includeExtraColors && name.includes(`--${eccgui}-color-palette-extra-`))
+            );
+        },
+        removeDashPrefix: false,
+        returnObject: true,
+    }).customProperties();
+
+    const colorsFromPaletteValues = Object.values(colorsFromPalette) as string[];
+
+    const colorsFromPaletteWithEnoughDistance =
+        minimalColorDistance > 0
+            ? colorsFromPaletteValues.reduce((enoughDistance: string[], color: string) => {
+                  if (enoughDistance.includes(color)) {
+                      return enoughDistance.filter((checkColor) => {
+                          const distance = colorCalculateDistance({ color1: color, color2: checkColor });
+                          return checkColor === color || (distance && minimalColorDistance <= distance);
+                      });
+                  } else {
+                      return enoughDistance;
+                  }
+              }, colorsFromPaletteValues)
+            : colorsFromPaletteValues;
+
+    getEnabledColorsFromPaletteCache.set(
+        configId,
+        colorsFromPaletteWithEnoughDistance.map((color: string) => {
+            return Color(color);
+        })
+    );
+
+    return getEnabledColorsFromPaletteCache.get(configId)!;
+}
+
+function getColorcode(text: string): ColorOrFalse {
+    try {
+        return Color(text);
+    } catch {
+        return false;
+    }
+}
+
+interface textToColorOptions {
+    /** Stack of colors that are allowed to be returned. */
+    enabledColors: Color[] | "all" | getEnabledColorsProps;
+    /** Return input text if it represents a valid color string, e.g. `#000` or `black`. */
+    returnValidColorsDirectly: boolean;
+}
+
+interface textToColorProps {
+    text: string;
+    options?: textToColorOptions;
+}
+
+/**
+ * Map a text string to a color.
+ * It always returns the same color for a text as long as the options stay the same.
+ * It returns `false` in case there are no colors defined to chose from.
+ */
+export function textToColorHash({
+    text,
+    options = {
+        enabledColors: getEnabledColorsFromPalette({}),
+        returnValidColorsDirectly: false,
+    },
+}: textToColorProps): string | false {
+    let color = getColorcode(text);
+
+    if (options.returnValidColorsDirectly && color) {
+        // return color code for text because it was a valid color string
+        return color.hex().toString();
+    }
+
+    color = getColorcode(stringToHexColorHash(text)) as Color;
+
+    if (options.enabledColors === "all" && color) {
+        // all colors are allowed as return value
+        return color.hex().toString();
+    }
+
+    let enabledColors = [] as Color[];
+
+    if (Array.isArray(options.enabledColors)) {
+        enabledColors = options.enabledColors;
+    } else {
+        enabledColors = getEnabledColorsFromPalette(options.enabledColors as getEnabledColorsProps);
+    }
+
+    if (enabledColors.length === 0) {
+        // eslint-disable-next-line no-console
+        console.warn("textToColorHash functionaliy need enabledColors list with at least 1 color.");
+        return false;
+    }
+
+    return nearestColorNeighbour(color, enabledColors as Color[])
+        .hex()
+        .toString();
+}
+
+function stringToIntegerHash(inputString: string): number {
+    /* this function is idempotend, meaning it retrieves the same result for the same input
+    no matter how many times it's called */
+    // Convert the string to a hash code
+    let hashCode = 0;
+    for (let i = 0; i < inputString.length; i++) {
+        hashCode = (hashCode << 5) - hashCode + inputString.charCodeAt(i);
+        hashCode &= hashCode; // Convert to 32bit integer
+    }
+    return hashCode;
+}
+
+function integerToHexColor(number: number): string {
+    // Convert the hash code to a positive number (32unsigned)
+    const hash = Math.abs(number + Math.pow(31, 2));
+    // Convert the number to a hex color (excluding white)
+    const hexColor = "#" + (hash % 0xffffff).toString(16).padStart(6, "0");
+    return hexColor;
+}
+
+function stringToHexColorHash(inputString: string): string {
+    const integerHash = stringToIntegerHash(inputString);
+    return integerToHexColor(integerHash);
+}
+
+function nearestColorNeighbour(color: Color, enabledColors: Color[]): Color {
+    const nearestNeighbour = enabledColors.reduce(
+        (nearestColor, enabledColorsItem) => {
+            const distance = colorCalculateDistance({
+                color1: color,
+                color2: enabledColorsItem,
+            });
+            return distance && distance < nearestColor.distance
+                ? {
+                      distance,
+                      color: enabledColorsItem,
+                  }
+                : nearestColor;
+        },
+        {
+            distance: Number.POSITIVE_INFINITY,
+            color: enabledColors[0],
+        }
+    );
+    return nearestNeighbour.color;
+}

src/configuration/constants.ts

@@ -1,2 +1,4 @@
 // basic vars
 export const CLASSPREFIX = "eccgui";
+export const COLORMINDISTANCE = 10;
+export const COLORMINCONTRAST = 4;