@qoretechnologies/reqore 0.78.6-pr.715.gdfefa70 → 0.78.7-pr.717.gae33bdc

package/dist/helpers/colors.js

@@ -1,10 +1,84 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getGradientMix = exports.getNthGradientColor = exports.buildGradientColorsFromString = exports.createEffectGradient = exports.getColorFromMaybeString = exports.getPanelHairlineColor = exports.getPanelBackgroundColor = exports.getThemePanelSurface = exports.getMainBackgroundColor = exports.getNotificationIntent = exports.mergeThemes = exports.buildTheme = exports.isValidSixCharHex = exports.getColorByBgColor = exports.getReadableAccentColor = exports.getOpaqueColor = exports.changeDarkness = exports.changeLightness = exports.getMainColor = exports.shouldDarken = exports.RGBAToHexA = exports.hexAToRGBA = exports.getRGBAFromHex = exports.percentToHexAlpha = exports.isAchromatic = exports.getReadableColorFrom = exports.getReadableColor = void 0;
+exports.getGradientColorList = exports.getGradientMix = exports.getNthGradientColor = exports.buildGradientColorsFromString = exports.createEffectGradient = exports.getColorFromMaybeString = exports.getMainBackgroundColor = exports.getNotificationIntent = exports.mergeThemes = exports.buildTheme = exports.isValidSixCharHex = exports.getColorByBgColor = exports.getReadableThemeColor = exports.getReadableTextColor = exports.getReadableIntentColor = exports.getThemeSurfaces = exports.getThemeSurface = exports.getReadableIconLook = exports.getReadableAccentColorOn = exports.getReadableAccentColor = exports.getOpaqueColor = exports.changeDarkness = exports.changeLightness = exports.getMainColor = exports.shouldDarken = exports.RGBAToHexA = exports.hexAToRGBA = exports.getRGBAFromHex = exports.percentToHexAlpha = exports.isAchromatic = exports.getReadableColorFrom = exports.getReadableTextOn = exports.getReadableFadedColor = exports.getReadableGroupOpacity = exports.getReadableAlpha = exports.getReadableColorOn = exports.getContrastRatio = exports.fadeColor = exports.getDrawnColor = exports.getSaturatedTint = exports.getColorAtAlpha = exports.isReadableColor = exports.LARGE_BOLD_TEXT_PX = exports.READABLE_ICON_CONTRAST = exports.READABLE_TEXT_CONTRAST = exports.getReadableColor = exports.getThemeColorKey = exports.cacheKey = exports.createColorCache = void 0;
 var lodash_1 = require("lodash");
 var polished_1 = require("polished");
 var colors_1 = require("../constants/colors");
 var theme_1 = require("../constants/theme");
+/**
+ * How many results each cached helper keeps. The color maths runs while components render - a button works out its
+ * text, its hover and its icons from what it is drawn on, a gradient each of its colors - and a page draws the same
+ * few colors over and over (a table of 500 buttons in one theme), so each helper remembers its last results. A
+ * page that keeps meeting new colors only ever holds this many: the one used least recently goes first.
+ */
+var COLOR_CACHE_SIZE = 2000;
+/**
+ * A helper's memory of its results (see `COLOR_CACHE_SIZE`): `remember(key, compute)`. Also for a component's
+ * color work that is a function of its key alone (an effect's gradient pass): not part of the package's API.
+ */
+var createColorCache = function () {
+    var results = new Map();
+    return function (key, compute) {
+        if (results.has(key)) {
+            var result_1 = results.get(key);
+            // the most recently used goes to the end, so the oldest is the first one out
+            results.delete(key);
+            results.set(key, result_1);
+            return result_1;
+        }
+        var result = compute();
+        results.set(key, result);
+        if (results.size > COLOR_CACHE_SIZE) {
+            results.delete(results.keys().next().value);
+        }
+        return result;
+    };
+};
+exports.createColorCache = createColorCache;
+/** One key for any list of a helper's arguments (colors, numbers, flags, lists of colors). */
+var cacheKey = function () {
+    var parts = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        parts[_i] = arguments[_i];
+    }
+    return parts.map(function (part) { return (Array.isArray(part) ? part.join(',') : String(part)); }).join('|');
+};
+exports.cacheKey = cacheKey;
+var intentKeys = new WeakMap();
+/**
+ * What of a theme the helpers that take one read: its main, the main it was made from, and its intents. The
+ * intents are written out once per intents object.
+ */
+var getThemeColorKey = function (theme) {
+    var intents = theme.intents;
+    var key = intents ? intentKeys.get(intents) : '';
+    if (key === undefined) {
+        key = JSON.stringify(intents);
+        intentKeys.set(intents, key);
+    }
+    return "".concat(theme.main, "|").concat(theme.originalMain, "|").concat(key);
+};
+exports.getThemeColorKey = getThemeColorKey;
 var getReadableColor = function (theme, ifLight, ifDark, dimmed, fallback) {
     var _a, _b;
     if ((_a = theme.text) === null || _a === void 0 ? void 0 : _a.color) {
@@ -16,16 +90,338 @@ var getReadableColor = function (theme, ifLight, ifDark, dimmed, fallback) {
     }
     var shouldDim = ((_b = theme.text) === null || _b === void 0 ? void 0 : _b.dim) && dimmed;
     var from = fallback || theme.main;
-    return (0, exports.getReadableColorFrom)(from, shouldDim, ifLight, ifDark);
+    // a translucent color (a theme made from the muted intent, say) is drawn over the theme it was made from
+    return (0, exports.getReadableColorFrom)(from, shouldDim, ifLight, ifDark, theme.originalMain);
 };
 exports.getReadableColor = getReadableColor;
-var getReadableColorFrom = function (from, dim, ifLight, ifDark) {
-    var returnIfLight = ifLight || (0, polished_1.lighten)(dim ? 0.05 : 0, colors_1.Colors.DARK);
-    var returnIfDark = ifDark || (0, polished_1.darken)(dim ? 0.05 : 0, colors_1.Colors.LIGHT);
-    var fixedColor = (0, exports.hexAToRGBA)(from);
-    return (0, polished_1.readableColor)(fixedColor, returnIfLight, returnIfDark, false);
+/**
+ * How far text has to stand out from what it is drawn on (WCAG 2.1 AA, 1.4.3): 4.5:1.
+ */
+exports.READABLE_TEXT_CONTRAST = 4.5;
+/**
+ * How far an icon (or any other graphic a control needs to be understood) and large text have to stand out from
+ * what they are drawn on (WCAG 2.1 AA, 1.4.11 and 1.4.3): 3:1.
+ */
+exports.READABLE_ICON_CONTRAST = 3;
+/** The least size (px) from which bold text is large in WCAG's sense (14pt), and needs to stand out by 3:1 only. */
+exports.LARGE_BOLD_TEXT_PX = 18.66;
+var rememberParts = (0, exports.createColorCache)();
+/**
+ * The red, green, blue and alpha of a color - any a browser and polished both read: a hex of 3, 4, 6 or 8 digits,
+ * `rgb()`, `rgba()`, `hsl()`, a named color. Undefined for one they do not (a CSS variable, `currentColor`, a
+ * typo), which is the caller's to draw as it is: the helpers below leave such a color alone instead of throwing
+ * while a component renders. `'transparent'` is black at no alpha: it draws nothing.
+ */
+var parseColor = function (color) {
+    if (typeof color !== 'string' || !color) {
+        return undefined;
+    }
+    return rememberParts(color, function () {
+        var _a;
+        if (color === 'transparent') {
+            return { red: 0, green: 0, blue: 0, alpha: 0 };
+        }
+        try {
+            var parsed = (0, polished_1.parseToRgb)(color);
+            return {
+                red: parsed.red,
+                green: parsed.green,
+                blue: parsed.blue,
+                alpha: (_a = parsed.alpha) !== null && _a !== void 0 ? _a : 1,
+            };
+        }
+        catch (_b) {
+            return undefined;
+        }
+    });
+};
+/** Whether the helpers can read `color` (see `parseColor`). */
+var isReadableColor = function (color) { return !!parseColor(color); };
+exports.isReadableColor = isReadableColor;
+/** Whether `color` is a color drawn opaque, which text can be read on. */
+var isOpaque = function (color) { var _a; return ((_a = parseColor(color)) === null || _a === void 0 ? void 0 : _a.alpha) === 1; };
+var toHexColor = function (_a) {
+    var red = _a.red, green = _a.green, blue = _a.blue;
+    return "#".concat([red, green, blue]
+        .map(function (part) {
+        return Math.round(Math.min(255, Math.max(0, part)))
+            .toString(16)
+            .padStart(2, '0');
+    })
+        .join(''));
+};
+var rememberAlphaColor = (0, exports.createColorCache)();
+/**
+ * `color` at `alpha`, as polished's `rgba(color, alpha)` writes it. A color it cannot read (a CSS variable,
+ * `currentColor`) is drawn as given, not thrown on: at an alpha below 1, mixed with nothing by the browser
+ * (`color-mix(in srgb, var(--brand) 20%, transparent)`), so a wash of it is still a wash and not the solid color
+ * the text on it is written in.
+ */
+var getColorAtAlpha = function (color, alpha) {
+    if (typeof color !== 'string' || !color) {
+        return color;
+    }
+    return rememberAlphaColor((0, exports.cacheKey)(color, alpha), function () {
+        if (parseColor(color)) {
+            return (0, polished_1.rgba)(color, alpha);
+        }
+        return alpha >= 1
+            ? color
+            : "color-mix(in srgb, ".concat(color, " ").concat(Math.round(Math.max(0, alpha) * 1000) / 10, "%, transparent)");
+    });
+};
+exports.getColorAtAlpha = getColorAtAlpha;
+var rememberTint = (0, exports.createColorCache)();
+/**
+ * `color` tinted toward white by `amount` and fully saturated: the light shade of it an outlined control (a minimal
+ * button, a minimal tag) starts its text from, before it is made to read (`getReadableAccentColorOn`). A translucent
+ * color is its own hue drawn opaque; one it cannot read is as it is.
+ */
+var getSaturatedTint = function (color, amount) {
+    var drawn = (0, exports.getDrawnColor)(color);
+    if (!isOpaque(drawn)) {
+        return drawn;
+    }
+    return rememberTint((0, exports.cacheKey)(drawn, amount), function () {
+        return (0, exports.getOpaqueColor)((0, polished_1.saturate)(1, (0, polished_1.tint)(amount, drawn)));
+    });
+};
+exports.getSaturatedTint = getSaturatedTint;
+var rememberDrawn = (0, exports.createColorCache)();
+/**
+ * `color` as it is drawn over `under`: a translucent color blended into what is under it, the way the browser
+ * draws it, and an opaque one as it is. Without `under` (or over one it cannot read), a translucent color counts as
+ * its own hue drawn opaque. An opaque six-digit hex - except for a color that draws nothing there
+ * (`'transparent'` with nothing under it) or one it cannot read (a CSS variable), which comes back as it is given.
+ */
+var getDrawnColor = function (color, under) {
+    return rememberDrawn((0, exports.cacheKey)(color, under), function () {
+        var top = parseColor(color);
+        if (!top) {
+            return color;
+        }
+        var bottom = top.alpha < 1 && under ? parseColor((0, exports.getDrawnColor)(under)) : undefined;
+        if (!bottom || bottom.alpha < 1) {
+            // nothing under it that can be read: its own hue, if it draws anything at all
+            return top.alpha > 0 ? toHexColor(top) : color;
+        }
+        var blend = function (above, below) { return above * top.alpha + below * (1 - top.alpha); };
+        return toHexColor({
+            red: blend(top.red, bottom.red),
+            green: blend(top.green, bottom.green),
+            blue: blend(top.blue, bottom.blue),
+            alpha: 1,
+        });
+    });
+};
+exports.getDrawnColor = getDrawnColor;
+/**
+ * `color` at `opacity` of the alpha it already has: a translucent color (a theme made from the muted intent) drawn
+ * at a panel's opacity stays as translucent, and more. `rgba(color, opacity)` replaced its alpha, so a panel in the
+ * muted intent's near-white drawn at 19% was drawn near-white and opaque. A color it cannot read is as it is.
+ */
+var fadeColor = function (color, opacity) {
+    var parts = parseColor(color);
+    if (!parts) {
+        return color;
+    }
+    return (0, polished_1.rgba)(parts.red, parts.green, parts.blue, parts.alpha * opacity);
+};
+exports.fadeColor = fadeColor;
+/**
+ * The WCAG relative luminance of an opaque color, not rounded: polished's `getLuminance` rounds to three decimals,
+ * which moves a ratio near a threshold across it (`#595959` on black is 2.998:1, not 3).
+ */
+var getRelativeLuminance = function (_a) {
+    var red = _a.red, green = _a.green, blue = _a.blue;
+    var linear = function (channel) {
+        var value = channel / 255;
+        return value <= 0.03928 ? value / 12.92 : Math.pow(((value + 0.055) / 1.055), 2.4);
+    };
+    return 0.2126 * linear(red) + 0.7152 * linear(green) + 0.0722 * linear(blue);
+};
+var rememberContrast = (0, exports.createColorCache)();
+/**
+ * The WCAG contrast ratio of two colors, each drawn opaque: from 1 to 21, not rounded. NaN when either cannot be
+ * read or draws nothing (a CSS variable, `'transparent'`): there is no telling how far it stands out.
+ */
+var getContrastRatio = function (first, second) {
+    return rememberContrast((0, exports.cacheKey)(first, second), function () {
+        var one = parseColor((0, exports.getDrawnColor)(first));
+        var other = parseColor((0, exports.getDrawnColor)(second));
+        if (!one || !other || one.alpha < 1 || other.alpha < 1) {
+            return NaN;
+        }
+        var _a = [getRelativeLuminance(one), getRelativeLuminance(other)].sort(function (a, b) { return b - a; }), lighter = _a[0], darker = _a[1];
+        return (lighter + 0.05) / (darker + 0.05);
+    });
+};
+exports.getContrastRatio = getContrastRatio;
+/** The worst contrast `color` has with any of `backgrounds`. */
+var getWorstContrast = function (color, backgrounds) {
+    return Math.min.apply(Math, backgrounds.map(function (background) { return (0, exports.getContrastRatio)(color, background); }));
+};
+/** Of `colors`, as each is drawn over `under`, those text can be read on: opaque, and colors the helpers read. */
+var getReadableSurfaces = function (colors, under) {
+    return colors.map(function (color) { return (0, exports.getDrawnColor)(color, under); }).filter(function (color) { return isOpaque(color); });
+};
+// the theme's text colors, a shade softer (`dim`)
+var DIM_ON_LIGHT = (0, polished_1.lighten)(0.05, colors_1.Colors.DARK);
+var DIM_ON_DARK = (0, polished_1.darken)(0.05, colors_1.Colors.LIGHT);
+var rememberReadableOn = (0, exports.createColorCache)();
+/**
+ * The text color that reads on every one of `backgrounds` (each drawn over `under` when it is translucent - the
+ * colors of a gradient, or a single surface): of the text colors for a light and for a dark background (`ifLight`,
+ * `ifDark`; black and white, a shade softer when `dim`), the one that stands out more. When even that one does not
+ * reach 4.5:1, a color the caller gave stays theirs (the better of their pair); the default shades give way to pure
+ * black or white, whichever stands out more: a dimmed shade is a nicety, being read is not. A background it cannot
+ * read is left out; with none left, the text for a dark background (Reqore's default theme).
+ */
+var getReadableColorOn = function (backgrounds, dim, ifLight, ifDark, under) {
+    return rememberReadableOn((0, exports.cacheKey)(backgrounds, dim, ifLight, ifDark, under), function () {
+        var surfaces = getReadableSurfaces(backgrounds, under);
+        var onLight = ifLight || (dim ? DIM_ON_LIGHT : colors_1.Colors.DARK);
+        var onDark = ifDark || (dim ? DIM_ON_DARK : colors_1.Colors.LIGHT);
+        if (!surfaces.length) {
+            return onDark;
+        }
+        var preferred = getWorstContrast(onLight, surfaces) >= getWorstContrast(onDark, surfaces) ? onLight : onDark;
+        if (getWorstContrast(preferred, surfaces) >= exports.READABLE_TEXT_CONTRAST ||
+            (preferred === onLight ? !!ifLight : !!ifDark)) {
+            return preferred;
+        }
+        return getWorstContrast(colors_1.Colors.DARK, surfaces) >= getWorstContrast(colors_1.Colors.LIGHT, surfaces)
+            ? colors_1.Colors.DARK
+            : colors_1.Colors.LIGHT;
+    });
+};
+exports.getReadableColorOn = getReadableColorOn;
+/** The contrast of `color` (its red, green and blue), drawn at `alpha` over the opaque `background`, with it. */
+var getContrastAtAlpha = function (_a, background, alpha) {
+    var red = _a.red, green = _a.green, blue = _a.blue;
+    return (0, exports.getContrastRatio)((0, exports.getDrawnColor)((0, polished_1.rgba)(red, green, blue, alpha), background), background);
+};
+/** How far past the ratio `getReadableAlpha` aims: see there. */
+var READABLE_ALPHA_MARGIN = 0.1;
+/**
+ * The least alpha (or opacity), from `alpha` up, at which `color` drawn over `background` (each of them, for a list)
+ * still stands out from it by `minContrast`: secondary text or an icon fades only as far as it can and still be read.
+ * `alpha` itself when it already reads; 1 when even the full color does not, which is for whoever chose that color to
+ * fix. A color or a background it cannot read (none given, a CSS variable) leaves `alpha` as it is: there is no
+ * telling how far it stands out.
+ */
+var getReadableAlpha = function (color, background, alpha, minContrast) {
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    return Math.max.apply(Math, __spreadArray([alpha], (Array.isArray(background) ? background : [background]).map(function (each) {
+        return getReadableAlphaOn(color, each, alpha, minContrast);
+    }), false));
+};
+exports.getReadableAlpha = getReadableAlpha;
+/**
+ * The least alpha from `from` up to 1 at which `reads` holds, to a hundredth, rounded up: `reads` holds at 1 and not
+ * at `from`. The range in which it starts to hold is halved until it is less than half a hundredth wide.
+ */
+var leastReadingAlpha = function (from, reads) {
+    var low = from;
+    var high = 1;
+    while (high - low > 0.005) {
+        var middle = (low + high) / 2;
+        if (reads(middle)) {
+            high = middle;
+        }
+        else {
+            low = middle;
+        }
+    }
+    return Math.min(1, Math.ceil(high * 100) / 100);
+};
+var rememberAlpha = (0, exports.createColorCache)();
+var getReadableAlphaOn = function (color, background, alpha, ratio) {
+    return rememberAlpha((0, exports.cacheKey)(color, background, alpha, ratio), function () {
+        var parts = parseColor(color);
+        var surface = (0, exports.getDrawnColor)(background);
+        if (alpha >= 1 || !parts || !isOpaque(surface)) {
+            return alpha;
+        }
+        // A browser blends a translucent color a shade differently (an alpha of 255ths, its own rounding): an alpha
+        // that just reaches the ratio here can fall a hair short on the page, so it aims a little past it.
+        var minContrast = ratio + READABLE_ALPHA_MARGIN;
+        if (getContrastAtAlpha(parts, surface, alpha) >= minContrast) {
+            return alpha;
+        }
+        if (getContrastAtAlpha(parts, surface, 1) < minContrast) {
+            return 1;
+        }
+        return leastReadingAlpha(alpha, function (at) { return getContrastAtAlpha(parts, surface, at) >= minContrast; });
+    });
+};
+/**
+ * How far a group drawn as a whole (`opacity` on it: an idle rail resting dim) can be faded over `under` and every
+ * one of `marks` in it still stand out from what it is drawn on by `minContrast`: `opacity`, or as little more as
+ * it takes. Faded, a mark and what it is on both fade into `under`, so they draw closer together.
+ */
+var getReadableGroupOpacity = function (marks, under, opacity, minContrast) {
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    var page = (0, exports.getDrawnColor)(under);
+    // aims a little past the ratio, as getReadableAlpha does: the browser blends a shade differently
+    var target = minContrast + READABLE_ALPHA_MARGIN;
+    // a mark, or what it is on, that cannot be read (a CSS variable) cannot be measured: it is left out
+    var drawn = marks
+        .map(function (_a) {
+        var color = _a.color, alpha = _a.alpha, on = _a.on;
+        var fill = (0, exports.getDrawnColor)(on);
+        return { fill: fill, mark: (0, exports.getDrawnColor)((0, exports.fadeColor)(color, alpha), fill) };
+    })
+        .filter(function (_a) {
+        var fill = _a.fill, mark = _a.mark;
+        return isOpaque(fill) && isOpaque(mark);
+    });
+    if (!isOpaque(page) || !drawn.length) {
+        return opacity;
+    }
+    var reads = function (at) {
+        return drawn.every(function (_a) {
+            var fill = _a.fill, mark = _a.mark;
+            return (0, exports.getContrastRatio)((0, exports.getDrawnColor)((0, polished_1.rgba)(mark, at), page), (0, exports.getDrawnColor)((0, polished_1.rgba)(fill, at), page)) >=
+                target;
+        });
+    };
+    if (opacity >= 1 || reads(opacity)) {
+        return opacity;
+    }
+    if (!reads(1)) {
+        return 1;
+    }
+    return leastReadingAlpha(opacity, reads);
+};
+exports.getReadableGroupOpacity = getReadableGroupOpacity;
+/** `color` at `alpha`, or at as much more as it needs to stand out from `background` (`getReadableAlpha`). */
+var getReadableFadedColor = function (color, background, alpha, minContrast) {
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    return isOpaque((0, exports.getDrawnColor)(color))
+        ? (0, polished_1.rgba)((0, exports.getDrawnColor)(color), (0, exports.getReadableAlpha)(color, background, alpha, minContrast))
+        : color;
+};
+exports.getReadableFadedColor = getReadableFadedColor;
+/**
+ * A theme's text color on every one of `backgrounds` (what a component is drawn in - each color of its gradient):
+ * the theme's own text color when it names one, else the one that reads on all of them (`getReadableColorOn`),
+ * dimmed when the theme dims its text.
+ */
+var getReadableTextOn = function (theme, backgrounds, dimmed) {
+    var _a, _b;
+    if (dimmed === void 0) { dimmed = true; }
+    return ((_a = theme.text) === null || _a === void 0 ? void 0 : _a.color)
+        ? (0, exports.getReadableColor)(theme, undefined, undefined, dimmed)
+        : (0, exports.getReadableColorOn)(backgrounds, !!((_b = theme.text) === null || _b === void 0 ? void 0 : _b.dim) && dimmed);
 };
+exports.getReadableTextOn = getReadableTextOn;
+/**
+ * The text color that reads on `from` (drawn over `under` when it is translucent): see `getReadableColorOn`.
+ */
+var getReadableColorFrom = function (from, dim, ifLight, ifDark, under) { return (0, exports.getReadableColorOn)([from], dim, ifLight, ifDark, under); };
 exports.getReadableColorFrom = getReadableColorFrom;
+/** Whether `color` is a gray (black and white included); false for one it cannot read. */
 var isAchromatic = function (color) {
     var fixedColor = (0, exports.getRGBAFromHex)(color);
     return fixedColor.r === fixedColor.g && fixedColor.g === fixedColor.b;
@@ -38,31 +434,59 @@ var percentToHexAlpha = function (p) {
     return hexValue.padStart(2, '0').toUpperCase(); // format with leading 0 and upper case characters
 };
 exports.percentToHexAlpha = percentToHexAlpha;
+/** A hex color of 3, 4, 6 or 8 digits: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`. */
+var HEX_COLOR = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/**
+ * A hex color in its long form, as CSS reads a short one - each digit doubled: `#fdc` is `#ffddcc`, `#f00a` is
+ * `#ff0000aa`. A long one, or anything that is not a hex color, as it is.
+ */
+var expandHexColor = function (color) {
+    return HEX_COLOR.test(color) && color.length <= 5
+        ? "#".concat(Array.from(color.slice(1), function (digit) { return digit + digit; }).join(''))
+        : color;
+};
+var NO_RGBA = { r: NaN, g: NaN, b: NaN, a: NaN };
+/**
+ * The red, green, blue (0-255) and alpha (0-1) of a color: a hex of 3, 4, 6 or 8 digits, `rgb()`/`rgba()`, or any
+ * other color polished reads (`hsl()`, a named one). NaN in each for one it cannot read (a CSS variable).
+ *
+ * A short hex is each of its digits doubled (`#fdc` is `#ffddcc`). It was repeated (`#fdcfdc`, another hue), and
+ * polished writes the colors it works out short wherever it can, so a readable shade made from one of them took
+ * the wrong hue: a minimal button in `#ff5500` had lilac text instead of peach.
+ */
 var getRGBAFromHex = function (color) {
-    var hexColor = color;
+    if (typeof color !== 'string') {
+        return NO_RGBA;
+    }
     // If this is already an rgba color, we need to convert it to hex
-    if (color.startsWith('rgba')) {
-        hexColor = (0, exports.RGBAToHexA)(color);
+    var hexColor = expandHexColor(color.startsWith('rgba') ? (0, exports.RGBAToHexA)(color) : color);
+    if (!HEX_COLOR.test(hexColor)) {
+        var parts = parseColor(color);
+        return parts ? { r: parts.red, g: parts.green, b: parts.blue, a: parts.alpha } : NO_RGBA;
     }
-    var colorWithAlpha = hexColor.length === 4 ? hexColor + hexColor.slice(1, 4) : hexColor;
-    var r = parseInt(colorWithAlpha.slice(1, 3), 16);
-    var g = parseInt(colorWithAlpha.slice(3, 5), 16);
-    var b = parseInt(colorWithAlpha.slice(5, 7), 16);
-    var a = parseInt(colorWithAlpha.slice(7, 9) || 'ff', 16) / 255;
+    var r = parseInt(hexColor.slice(1, 3), 16);
+    var g = parseInt(hexColor.slice(3, 5), 16);
+    var b = parseInt(hexColor.slice(5, 7), 16);
+    var a = parseInt(hexColor.slice(7, 9) || 'ff', 16) / 255;
     return { r: r, g: g, b: b, a: a };
 };
 exports.getRGBAFromHex = getRGBAFromHex;
+/** `hex` as `rgba(r, g, b, a)`; an `rgb()`/`rgba()` color, and one it cannot read, as it is. */
 var hexAToRGBA = function (hex) {
     // Check if this color is already in rgba format
-    if (hex.startsWith('rgb')) {
+    if (typeof hex !== 'string' || hex.startsWith('rgb')) {
         return hex;
     }
     var _a = (0, exports.getRGBAFromHex)(hex), r = _a.r, g = _a.g, b = _a.b, a = _a.a;
+    if (Number.isNaN(r)) {
+        return hex;
+    }
     return "rgba(".concat(r, ", ").concat(g, ", ").concat(b, ", ").concat(a.toFixed(2), ")");
 };
 exports.hexAToRGBA = hexAToRGBA;
 var RGBAToHexA = function (rgba, forceRemoveAlpha) {
     if (forceRemoveAlpha === void 0) { forceRemoveAlpha = false; }
+    // a hex already, of any length (`#f00a` too, which the parse below would write as `#NaN`)
     if ((0, exports.isValidSixCharHex)(rgba)) {
         return rgba;
     }
@@ -78,41 +502,50 @@ var RGBAToHexA = function (rgba, forceRemoveAlpha) {
             .join('')); // Puts the array to togehter to a string
 };
 exports.RGBAToHexA = RGBAToHexA;
+/** Whether `mainColor` is light (a lighter shade of it is made darker); false for one it cannot read. */
 var shouldDarken = function (mainColor) {
-    return (0, polished_1.getLuminance)((0, exports.hexAToRGBA)(mainColor)) > 0.2;
+    return (0, exports.isReadableColor)(mainColor) && (0, polished_1.getLuminance)((0, exports.hexAToRGBA)(mainColor)) > 0.2;
 };
 exports.shouldDarken = shouldDarken;
 var getMainColor = function (theme, component) { var _a; return ((_a = theme[component]) === null || _a === void 0 ? void 0 : _a.main) || theme.main; };
 exports.getMainColor = getMainColor;
 //export const changeBasedOnContrast = (color: string, lightness?: number): string =>
-var changeLightness = function (color, lightness) {
-    var fixedColor = (0, exports.hexAToRGBA)(color);
-    return lightness
-        ? (0, exports.shouldDarken)(fixedColor)
+var rememberLightness = (0, exports.createColorCache)();
+/**
+ * `color` moved by `lightness` away from what it is (`towardContrast`: a light color darker, a dark one lighter)
+ * or toward it. A color it cannot read is as it is.
+ */
+var shiftLightness = function (color, lightness, towardContrast) {
+    if (!lightness || !(0, exports.isReadableColor)(color)) {
+        return color;
+    }
+    return rememberLightness((0, exports.cacheKey)(color, lightness, towardContrast), function () {
+        var fixedColor = (0, exports.hexAToRGBA)(color);
+        return ((0, exports.shouldDarken)(fixedColor) === towardContrast
             ? (0, polished_1.darken)(lightness, fixedColor)
-            : (0, polished_1.lighten)(lightness, fixedColor)
-        : color;
+            : (0, polished_1.lighten)(lightness, fixedColor));
+    });
+};
+var changeLightness = function (color, lightness) {
+    return shiftLightness(color, lightness, true);
 };
 exports.changeLightness = changeLightness;
 var changeDarkness = function (color, lightness) {
-    var fixedColor = (0, exports.hexAToRGBA)(color);
-    return lightness
-        ? (0, exports.shouldDarken)(fixedColor)
-            ? (0, polished_1.lighten)(lightness, fixedColor)
-            : (0, polished_1.darken)(lightness, fixedColor)
-        : color;
+    return shiftLightness(color, lightness, false);
 };
 exports.changeDarkness = changeDarkness;
 /**
  * The colour without its alpha channel, as a six-digit hex: `#e6e6e630` → `#e6e6e6`,
  * `rgba(10, 102, 64, 0.5)` → `#0a6640`. For colour maths that needs the hue a colour
  * is drawn in rather than how faintly it is drawn (Reqore's muted intent, for one, is
- * an eight-digit hex).
+ * an eight-digit hex). A color it cannot read (a CSS variable) is as it is.
  */
 var getOpaqueColor = function (color) {
     var _a = (0, exports.getRGBAFromHex)(color), r = _a.r, g = _a.g, b = _a.b;
-    var toHex = function (value) { return value.toString(16).padStart(2, '0'); };
-    return "#".concat(toHex(r)).concat(toHex(g)).concat(toHex(b));
+    if (Number.isNaN(r)) {
+        return color;
+    }
+    return toHexColor({ red: r, green: g, blue: b, alpha: 1 });
 };
 exports.getOpaqueColor = getOpaqueColor;
 /**
@@ -126,26 +559,140 @@ exports.getOpaqueColor = getOpaqueColor;
  * ends at white or black, which always can.
  */
 var getReadableAccentColor = function (color, background, minContrast) {
-    if (minContrast === void 0) { minContrast = 4.5; }
-    var surface = (0, exports.getOpaqueColor)(background);
-    var onLight = (0, exports.shouldDarken)(surface);
-    var accent = (0, exports.getOpaqueColor)(color);
-    // 25 steps of 4% lightness cover the whole range, so the loop always ends.
-    for (var step = 0; step < 25 && (0, polished_1.getContrast)(accent, surface) < minContrast; step++) {
-        accent = (onLight ? (0, polished_1.darken)(0.04, accent) : (0, polished_1.lighten)(0.04, accent));
-    }
-    return accent;
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    return (0, exports.getReadableAccentColorOn)(color, [background], minContrast);
 };
 exports.getReadableAccentColor = getReadableAccentColor;
+var rememberAccent = (0, exports.createColorCache)();
+/**
+ * `color` in the shade that stands out by `minContrast` from every one of `backgrounds` (see
+ * `getReadableAccentColor`): moved toward whichever of white and black stands out more from the worst of them, until
+ * it stands out from all of them - or is that white or black, when nothing does. Always a six-digit hex; a color it
+ * cannot read is as it is, and a background it cannot read is left out.
+ */
+var getReadableAccentColorOn = function (color, backgrounds, minContrast) {
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    var start = (0, exports.getOpaqueColor)(color);
+    if (!isOpaque(start)) {
+        return start;
+    }
+    return rememberAccent((0, exports.cacheKey)(start, backgrounds, minContrast), function () {
+        var surfaces = backgrounds
+            .map(function (background) { return (0, exports.getOpaqueColor)(background); })
+            .filter(function (surface) { return isOpaque(surface); });
+        var worst = function (candidate) {
+            return Math.min.apply(Math, surfaces.map(function (surface) { return (0, exports.getContrastRatio)(candidate, surface); }));
+        };
+        var lighter = worst(colors_1.Colors.LIGHT) >= worst(colors_1.Colors.DARK);
+        var accent = start;
+        // 25 steps of 4% lightness cover the whole range, so the loop always ends.
+        for (var step = 0; step < 25 && surfaces.length && worst(accent) < minContrast; step++) {
+            accent = (lighter ? (0, polished_1.lighten)(0.04, accent) : (0, polished_1.darken)(0.04, accent));
+        }
+        // polished writes a color short where it can (`#fff`): the long form, for whoever adds an alpha to it
+        return (0, exports.getOpaqueColor)(accent);
+    });
+};
+exports.getReadableAccentColorOn = getReadableAccentColorOn;
+/**
+ * How a control draws an icon on `backgrounds` (what it is drawn on: one color, or each it may be) beside its `text`:
+ * in its own `color` or else in the text color it inherits; at `opacity`, or as much more as it needs to stand out
+ * by 3:1. A theme's color (an intent, the theme's main, a shade of one) is drawn in the shade of it that stands
+ * out by 3:1; any other color (an explicit hex) as it is given, as a standalone `ReqoreIcon` draws it. `color` is
+ * undefined when the icon inherits the text color.
+ */
+var getReadableIconLook = function (theme, backgrounds, text, opacity, color) {
+    if (opacity === void 0) { opacity = 1; }
+    var iconColor = color
+        ? (0, exports.getReadableThemeColor)(theme, color, exports.READABLE_ICON_CONTRAST, undefined, backgrounds)
+        : undefined;
+    return {
+        color: iconColor,
+        opacity: (0, exports.getReadableAlpha)(iconColor !== null && iconColor !== void 0 ? iconColor : text, backgrounds, opacity, exports.READABLE_ICON_CONTRAST),
+    };
+};
+exports.getReadableIconLook = getReadableIconLook;
+/**
+ * What a component is drawn on: `surface`, when a component around it has said (`useReqoreSurface`), or else the
+ * surface of the theme it was picked in - the layout's, the theme's main a step lighter (`getMainBackgroundColor`).
+ * One color: the first of a gradient's (`getThemeSurfaces` gives every one).
+ */
+var getThemeSurface = function (theme, surface) { return (0, exports.getThemeSurfaces)(theme, surface)[0]; };
+exports.getThemeSurface = getThemeSurface;
+/**
+ * Every color a component is drawn on (see `getThemeSurface`): each of a gradient's, or the one. A color that draws
+ * nothing (`'transparent'`) or that cannot be read (a CSS variable) is no surface to read on and is left out; with
+ * none left, the theme's.
+ */
+var getThemeSurfaces = function (theme, surface) {
+    var given = getReadableSurfaces(Array.isArray(surface) ? surface : surface ? [surface] : []);
+    return given.length
+        ? given
+        : [(0, exports.getDrawnColor)((0, exports.changeLightness)(theme.originalMain || theme.main, 0.02))];
+};
+exports.getThemeSurfaces = getThemeSurfaces;
+var rememberIntentColor = (0, exports.createColorCache)();
+var rememberThemeColor = (0, exports.createColorCache)();
+/**
+ * Text (or an icon, at `minContrast` 3) in an intent's color on what it is drawn on (`surface`, or the theme's: see
+ * `getThemeSurface`): the intent in the shade that stands out there - a warning stays orange, an orange light enough
+ * to read on a dark theme. A translucent intent (muted) is drawn over that surface first.
+ */
+var getReadableIntentColor = function (theme, intent, minContrast, surface) {
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    return rememberIntentColor((0, exports.cacheKey)((0, exports.getThemeColorKey)(theme), intent, minContrast, surface), function () {
+        var unders = (0, exports.getThemeSurfaces)(theme, surface);
+        return (0, exports.getReadableAccentColorOn)((0, exports.getDrawnColor)(theme.intents[intent] || unders[0], unders[0]), unders, minContrast);
+    });
+};
+exports.getReadableIntentColor = getReadableIntentColor;
+/**
+ * The color a span, a paragraph or a link writes its text in: an intent in a shade of it that reads on what the text
+ * is drawn on (`surface`, or the theme's), else the theme's text color, else what it inherits.
+ */
+var getReadableTextColor = function (theme, intent, surface) {
+    var _a;
+    return intent
+        ? (0, exports.getReadableIntentColor)(theme, intent, undefined, surface)
+        : ((_a = theme.text) === null || _a === void 0 ? void 0 : _a.color) || 'inherit';
+};
+exports.getReadableTextColor = getReadableTextColor;
+/**
+ * A theme's color - an intent, the theme's main, a shade of one ('info', 'success:lighten:5') - in the shade of it
+ * that stands out by `minContrast` from what it is drawn on: `backgrounds` when they are known (a tag's fill, each
+ * color of a gradient), else `surface` or the theme's (`getThemeSurface`). The theme picks the hue, not how faint
+ * it is. Any other color is as it is given.
+ */
+var getReadableThemeColor = function (theme, color, minContrast, surface, backgrounds) {
+    var _a;
+    if (minContrast === void 0) { minContrast = exports.READABLE_TEXT_CONTRAST; }
+    var resolved = (0, exports.getColorFromMaybeString)(theme, color);
+    var base = typeof color === 'string' ? color.split(':')[0] : undefined;
+    if (!resolved || !base || (base !== 'main' && !((_a = theme.intents) === null || _a === void 0 ? void 0 : _a[base]))) {
+        return resolved;
+    }
+    return rememberThemeColor((0, exports.cacheKey)(resolved, minContrast, (backgrounds === null || backgrounds === void 0 ? void 0 : backgrounds.length) ? backgrounds : '', surface, theme.originalMain, theme.main), function () {
+        var under = (backgrounds === null || backgrounds === void 0 ? void 0 : backgrounds.length) ? backgrounds : (0, exports.getThemeSurfaces)(theme, surface);
+        return (0, exports.getReadableAccentColorOn)((0, exports.getDrawnColor)(resolved, under[0]), under, minContrast);
+    });
+};
+exports.getReadableThemeColor = getReadableThemeColor;
+/**
+ * Black or white for a background, by its value in the long form (a short hex, `#fff`, was read as the number
+ * `0xfff`: white text on white). Empty for no background; white for one it cannot read.
+ */
 var getColorByBgColor = function (bgColor) {
     if (!bgColor) {
         return '';
     }
-    return parseInt(bgColor.replace('#', ''), 16) > 0xffffff / 2 ? '#000000' : '#ffffff';
+    return parseInt((0, exports.getOpaqueColor)(bgColor).replace('#', ''), 16) > 0xffffff / 2
+        ? '#000000'
+        : '#ffffff';
 };
 exports.getColorByBgColor = getColorByBgColor;
+/** A hex color of 3, 4, 6 or 8 digits (the name is older than the rule): one CSS and the helpers read. */
 var isValidSixCharHex = function (hex) {
-    return /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3}|[A-Fa-f0-9]{8})$/.test(hex);
+    return typeof hex === 'string' && HEX_COLOR.test(hex);
 };
 exports.isValidSixCharHex = isValidSixCharHex;
 var buildTheme = function (theme) {
@@ -212,56 +759,67 @@ var getMainBackgroundColor = function (theme) {
 };
 exports.getMainBackgroundColor = getMainBackgroundColor;
 /**
- * The `theme.panel` surface and hairline — for a component whose own surface is NOT customised.
- * A `customTheme` with a `main`, an intent, or an inherited custom theme moves `theme.main` away
- * from `theme.originalMain` (see `mergeThemes`); such a component keeps its derived colours.
+ * Whether `color` is one CSS draws though Reqore has no name for it: a color function (`var(--brand)`, `hsl()`,
+ * `color-mix()`), `currentColor`, or a color polished reads (a named one, `red`).
  */
-var getThemePanelSurface = function (theme) {
-    return theme.panel && (!theme.originalMain || theme.main === theme.originalMain)
-        ? theme.panel
-        : undefined;
+var isCssColor = function (color) {
+    return color.includes('(') || /^currentcolor$/i.test(color) || (0, exports.isReadableColor)(color);
 };
-exports.getThemePanelSurface = getThemePanelSurface;
-/** The surface a panel or panel-like container paints: `theme.panel.main`, or derived from `main`. */
-var getPanelBackgroundColor = function (theme) { var _a, _b; return (_b = (_a = (0, exports.getThemePanelSurface)(theme)) === null || _a === void 0 ? void 0 : _a.main) !== null && _b !== void 0 ? _b : (0, exports.changeDarkness)((0, exports.getMainBackgroundColor)(theme), 0.03); };
-exports.getPanelBackgroundColor = getPanelBackgroundColor;
-/** The neutral 1px edge of a panel or panel-like container: `theme.panel.border`, or derived. */
-var getPanelHairlineColor = function (theme) { var _a, _b; return (_b = (_a = (0, exports.getThemePanelSurface)(theme)) === null || _a === void 0 ? void 0 : _a.border) !== null && _b !== void 0 ? _b : (0, exports.changeLightness)((0, exports.getMainBackgroundColor)(theme), 0.08); };
-exports.getPanelHairlineColor = getPanelHairlineColor;
+var rememberColor = (0, exports.createColorCache)();
+/**
+ * The color `color` names: an intent, the theme's main (`main`, or nothing before the first colon), a hex (a short
+ * one with an alpha, `#f00a`, in its long form), or `transparent` (the theme's original main), lightened or
+ * darkened by a number of steps and drawn at an alpha (`info:lighten:2:0.5`). A color CSS draws but Reqore has no
+ * name for (`red`, `var(--brand)`, `currentColor`) is as it is given, and so is a color that cannot be lightened (an
+ * intent that is a CSS variable); a name nothing knows is undefined.
+ */
 var getColorFromMaybeString = function (theme, color) {
-    if (!color) {
+    var _a;
+    if (!color || typeof color !== 'string') {
         return undefined;
     }
     if (color.startsWith('rgba')) {
         return (0, exports.RGBAToHexA)(color);
     }
-    var _a = color.split(':'), providedColor = _a[0], shading = _a[1], _b = _a[2], multiplier = _b === void 0 ? 1 : _b, _c = _a[3], alpha = _c === void 0 ? 1 : _c;
+    var _b = color.split(':'), providedColor = _b[0], shading = _b[1], _c = _b[2], multiplier = _c === void 0 ? 1 : _c, _d = _b[3], alpha = _d === void 0 ? 1 : _d;
     if (providedColor === 'transparent') {
         return theme.originalMain;
     }
-    // First we need to get the actual color
-    var _color;
-    if (!providedColor || providedColor === 'main') {
-        _color = theme.main;
-    }
-    if (theme.intents[providedColor]) {
-        _color = theme.intents[providedColor];
-    }
-    if ((0, exports.isValidSixCharHex)(providedColor)) {
-        _color = providedColor;
-    }
-    if (shading) {
-        if (shading === 'lighten') {
-            _color = (0, polished_1.lighten)(0.033 * multiplier, _color);
+    return rememberColor((0, exports.cacheKey)(color, theme.main, theme.originalMain, (_a = theme.intents) === null || _a === void 0 ? void 0 : _a[providedColor]), function () {
+        var _a;
+        // First we need to get the actual color
+        var _color;
+        if (!providedColor || providedColor === 'main') {
+            _color = theme.main;
         }
-        else if (shading === 'darken') {
-            _color = (0, polished_1.darken)(0.033 * multiplier, _color);
+        if ((_a = theme.intents) === null || _a === void 0 ? void 0 : _a[providedColor]) {
+            _color = theme.intents[providedColor];
         }
-    }
-    if (_color && _color.length === 7 && alpha < 1) {
-        _color = (0, exports.RGBAToHexA)((0, polished_1.transparentize)(1 - alpha, _color));
-    }
-    return _color;
+        if (HEX_COLOR.test(providedColor)) {
+            // a short hex with an alpha (`#f00a`) in its long form; any other hex as it is
+            _color = (providedColor.length === 5 ? expandHexColor(providedColor) : providedColor);
+        }
+        else if (!_color && providedColor && isCssColor(providedColor)) {
+            _color = providedColor;
+        }
+        // a color that cannot be read (a CSS variable) cannot be shaded either: it is drawn as it is
+        if (!(0, exports.isReadableColor)(_color)) {
+            return _color;
+        }
+        if (shading) {
+            if (shading === 'lighten') {
+                _color = (0, polished_1.lighten)(0.033 * multiplier, _color);
+            }
+            else if (shading === 'darken') {
+                _color = (0, polished_1.darken)(0.033 * multiplier, _color);
+            }
+        }
+        // an opaque hex (polished writes a short one where it can) drawn at an alpha
+        if ((_color.length === 7 || _color.length === 4) && alpha < 1) {
+            _color = (0, exports.RGBAToHexA)((0, polished_1.transparentize)(1 - alpha, _color));
+        }
+        return _color;
+    });
 };
 exports.getColorFromMaybeString = getColorFromMaybeString;
 var createEffectGradient = function (theme, colors, lighten, minimal, active, transparent) {
@@ -271,36 +829,82 @@ var createEffectGradient = function (theme, colors, lighten, minimal, active, tr
     if (!colors) {
         throw new Error('You need to provide colors');
     }
-    if (typeof colors === 'string') {
-        _colors = (0, exports.buildGradientColorsFromString)(theme, colors);
-    }
-    else {
-        _colors = colors;
-    }
-    return (0, lodash_1.reduce)(_colors, function (colorsString, color, percentage) {
-        return "".concat(colorsString, ", ").concat(transparent
-            ? active
-                ? theme.originalMain
-                : (0, exports.changeLightness)(theme.originalMain, lighten)
-            : minimal
-                ? (0, polished_1.rgba)((0, exports.changeLightness)((0, exports.getColorFromMaybeString)(theme, color), lighten), 0.25)
-                : (0, exports.changeLightness)((0, exports.getColorFromMaybeString)(theme, color), lighten), " ").concat(percentage, "%");
-    }, '');
+    return rememberEffectGradient((0, exports.cacheKey)((0, exports.getThemeColorKey)(theme), typeof colors === 'string' ? colors : JSON.stringify(colors), lighten, minimal, active, transparent), function () {
+        if (typeof colors === 'string') {
+            _colors = (0, exports.buildGradientColorsFromString)(theme, colors);
+        }
+        else {
+            _colors = colors;
+        }
+        return (0, lodash_1.reduce)(_colors, function (colorsString, color, percentage) {
+            // a color nothing knows draws nothing, rather than an `undefined` that drops the whole gradient
+            var stop = (0, exports.getColorFromMaybeString)(theme, color) || 'transparent';
+            return "".concat(colorsString, ", ").concat(transparent
+                ? active
+                    ? theme.originalMain
+                    : (0, exports.changeLightness)(theme.originalMain, lighten)
+                : minimal
+                    ? (0, exports.getColorAtAlpha)((0, exports.changeLightness)(stop, lighten), 0.25)
+                    : (0, exports.changeLightness)(stop, lighten), " ").concat(percentage, "%");
+        }, '');
+    });
 };
 exports.createEffectGradient = createEffectGradient;
+var rememberEffectGradient = (0, exports.createColorCache)();
+var rememberGradientColors = (0, exports.createColorCache)();
+/**
+ * A gradient made from one color (`'info'`, `'#0776cb'`): see `buildGradientShades`. A color it cannot read (a CSS
+ * variable) is the gradient's both ends.
+ */
 var buildGradientColorsFromString = function (theme, colorString) {
     if (!colorString) {
         throw new Error('You need to provide a color or intent');
     }
     var finalColor = (0, exports.getColorFromMaybeString)(theme, colorString);
-    var colorFrom = (0, exports.getColorFromMaybeString)(theme, "".concat(finalColor, ":lighten:5:1"));
-    var colorTo = (0, exports.getColorFromMaybeString)(theme, "".concat(finalColor, ":darken:5:1"));
+    if (!(0, exports.isReadableColor)(finalColor)) {
+        return { 0: finalColor, 100: finalColor };
+    }
+    // the shades depend only on the color: a copy, so a caller that changes it changes nobody else's
+    return __assign({}, rememberGradientColors(finalColor, function () { return buildGradientShades(theme, finalColor); }));
+};
+exports.buildGradientColorsFromString = buildGradientColorsFromString;
+var buildGradientShades = function (theme, finalColor) {
+    /* A lighter and a darker shade of the color, each as far as five steps from it - but only as far as the text
+       that reads on the color still reads on the shade: a gradient made from one color is a color text is put on,
+       and a blue lightened past where white reads on it was white text on a light blue at one end. */
+    var text = (0, exports.getReadableColorOn)([finalColor]);
+    // read at rest and a step lighter, as the effect draws it hovered or pressed
+    var readsOn = function (shade) {
+        return (0, exports.getContrastRatio)(text, shade) >= exports.READABLE_TEXT_CONTRAST &&
+            (0, exports.getContrastRatio)(text, (0, exports.changeLightness)(shade, 0.05)) >= exports.READABLE_TEXT_CONTRAST;
+    };
+    var getShade = function (shading) {
+        for (var steps = 5; steps > 0; steps--) {
+            var shade = (0, exports.getColorFromMaybeString)(theme, "".concat(finalColor, ":").concat(shading, ":").concat(steps, ":1"));
+            if (readsOn(shade)) {
+                return shade;
+            }
+        }
+        if (readsOn(finalColor)) {
+            return finalColor;
+        }
+        // the color itself does not read once lightened: as little the other way as it takes
+        var opposite = shading === 'lighten' ? 'darken' : 'lighten';
+        for (var steps = 1; steps <= 5; steps++) {
+            var shade = (0, exports.getColorFromMaybeString)(theme, "".concat(finalColor, ":").concat(opposite, ":").concat(steps, ":1"));
+            if (readsOn(shade)) {
+                return shade;
+            }
+        }
+        return finalColor;
+    };
+    var colorFrom = getShade('lighten');
+    var colorTo = getShade('darken');
     return {
         0: colorFrom,
         100: colorTo,
     };
 };
-exports.buildGradientColorsFromString = buildGradientColorsFromString;
 var getNthGradientColor = function (theme, colors, nth) {
     if (nth === void 0) { nth = 1; }
     var _colors = typeof colors === 'string' ? (0, exports.buildGradientColorsFromString)(theme, colors) : colors;
@@ -310,7 +914,16 @@ var getNthGradientColor = function (theme, colors, nth) {
     return undefined;
 };
 exports.getNthGradientColor = getNthGradientColor;
+var rememberGradientMix = (0, exports.createColorCache)();
 var getGradientMix = function (theme, colors, fallback) {
+    if (!colors) {
+        return fallback;
+    }
+    return rememberGradientMix((0, exports.cacheKey)((0, exports.getThemeColorKey)(theme), typeof colors === 'string' ? colors : JSON.stringify(colors), fallback), function () { return mixGradient(theme, colors, fallback); });
+};
+exports.getGradientMix = getGradientMix;
+/** The middle of a gradient, the mix of its first and last colors: see `getGradientMix`. */
+var mixGradient = function (theme, colors, fallback) {
     var _colors = typeof colors === 'string' ? (0, exports.buildGradientColorsFromString)(theme, colors) : colors;
     if (!_colors) {
         return fallback;
@@ -318,7 +931,30 @@ var getGradientMix = function (theme, colors, fallback) {
     // If there are more than 2 colors, we can't mix them, so we get the first and last color
     var gradientColor1 = (0, exports.getNthGradientColor)(theme, _colors);
     var gradientColor2 = (0, exports.getNthGradientColor)(theme, _colors, (0, lodash_1.size)(_colors));
-    return (0, exports.RGBAToHexA)((0, polished_1.mix)(0.5, gradientColor1 === '#00000000' ? theme.main : gradientColor1, gradientColor2 === '#00000000' ? theme.main : gradientColor2));
+    var first = gradientColor1 === '#00000000' ? theme.main : gradientColor1;
+    var last = gradientColor2 === '#00000000' ? theme.main : gradientColor2;
+    // colors it cannot read (a CSS variable) cannot be mixed: the first that can be, or the fallback
+    if (!(0, exports.isReadableColor)(first) || !(0, exports.isReadableColor)(last)) {
+        return [first, last].find(function (color) { return (0, exports.isReadableColor)(color); }) || fallback || first;
+    }
+    return (0, exports.RGBAToHexA)((0, polished_1.mix)(0.5, first, last));
 };
-exports.getGradientMix = getGradientMix;
+var rememberGradientList = (0, exports.createColorCache)();
+/**
+ * Each color a gradient is drawn in, as given (a translucent one stays translucent): what text on the gradient has
+ * to stand out from, every one of them.
+ */
+var getGradientColorList = function (theme, colors) {
+    if (!colors) {
+        return [];
+    }
+    // a copy: a caller that changes the list changes nobody else's
+    return __spreadArray([], rememberGradientList((0, exports.cacheKey)((0, exports.getThemeColorKey)(theme), typeof colors === 'string' ? colors : JSON.stringify(colors)), function () {
+        var _colors = typeof colors === 'string' ? (0, exports.buildGradientColorsFromString)(theme, colors) : colors;
+        return Object.values(_colors)
+            .map(function (color) { return (0, exports.getColorFromMaybeString)(theme, color); })
+            .filter(function (color) { return !!color; });
+    }), true);
+};
+exports.getGradientColorList = getGradientColorList;
 //# sourceMappingURL=colors.js.map