theme-vir 28.24.0 → 28.25.0

package/dist/color-theme/build-color-theme.d.ts

@@ -43,6 +43,17 @@ export type ArrayOrSelectParam<T extends PropertyKey> = ReadonlyArray<T> | Reado
 export declare const defaultLightThemePair: RequiredAndNotNull<NoRefColorInit>;
 /** @category Internal */
 export declare const defaultContrastLevels: Readonly<ArrayOrSelectParam<ContrastLevelName>>;
+/**
+ * Extra contrast levels generated by {@link buildColorTheme} beyond the standard `ContrastLevelName`
+ * values. `highest-contrast` always picks the palette color with the most contrast against the
+ * fixed color; `lowest-contrast` always picks the closest.
+ *
+ * @category Internal
+ */
+export declare enum ExtremeContrastLevel {
+    HighestContrast = "highest-contrast",
+    LowestContrast = "lowest-contrast"
+}
 /**
  * Options for {@link buildColorTheme}.
  *

package/dist/color-theme/build-color-theme.js

@@ -90,6 +90,55 @@ export const defaultLightThemePair = {
 };
 /** @category Internal */
 export const defaultContrastLevels = getEnumValues(ContrastLevelName);
+/**
+ * Extra contrast levels generated by {@link buildColorTheme} beyond the standard `ContrastLevelName`
+ * values. `highest-contrast` always picks the palette color with the most contrast against the
+ * fixed color; `lowest-contrast` always picks the closest.
+ *
+ * @category Internal
+ */
+export var ExtremeContrastLevel;
+(function (ExtremeContrastLevel) {
+    ExtremeContrastLevel["HighestContrast"] = "highest-contrast";
+    ExtremeContrastLevel["LowestContrast"] = "lowest-contrast";
+})(ExtremeContrastLevel || (ExtremeContrastLevel = {}));
+/**
+ * Picks the absolute lightest or darkest palette color based on which extreme produces the most (or
+ * least) contrast against the fixed color.
+ */
+function resolveExtremeContrastColor({ comparison, isHighestContrast, lightestColorString, darkestColorString, }) {
+    const paletteIsBackground = check.isArray(comparison.background);
+    const fixedColor = paletteIsBackground
+        ? comparison.foreground
+        : comparison.background;
+    const lightContrastParams = paletteIsBackground
+        ? {
+            foreground: fixedColor,
+            background: lightestColorString,
+        }
+        : {
+            foreground: lightestColorString,
+            background: fixedColor,
+        };
+    const darkContrastParams = paletteIsBackground
+        ? {
+            foreground: fixedColor,
+            background: darkestColorString,
+        }
+        : {
+            foreground: darkestColorString,
+            background: fixedColor,
+        };
+    const lightestContrast = Math.abs(calculateContrast(lightContrastParams).contrast);
+    const darkestContrast = Math.abs(calculateContrast(darkContrastParams).contrast);
+    return isHighestContrast
+        ? lightestContrast > darkestContrast
+            ? lightestColorString
+            : darkestColorString
+        : lightestContrast < darkestContrast
+            ? lightestColorString
+            : darkestColorString;
+}
 function findColorWithPreference(colors, desiredContrastLevel, preference, 
 /** Pre-computed contrast-against-white values per color string. Higher = darker. */
 lightnessProxies) {
@@ -140,6 +189,11 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
     const lightThemeColors = {};
     const darkThemeOverrides = {};
     // Compute these once outside the loop since they don't change
+    const allContrastLevels = [
+        ExtremeContrastLevel.HighestContrast,
+        ...contrastLevels,
+        ExtremeContrastLevel.LowestContrast,
+    ];
     const allCrosses = crossProduct({
         crossWith: [
             'color-in-foreground-light-mode',
@@ -151,7 +205,7 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
             'color-on-self-light-mode',
             'color-on-self-dark-mode',
         ],
-        contrast: contrastLevels,
+        contrast: allContrastLevels,
     });
     const defaultForegroundString = noRefColorInitToString(defaultTheme.foreground);
     const defaultBackgroundString = noRefColorInitToString(defaultTheme.background);
@@ -196,6 +250,15 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
             foreground: colorStrings,
             background: darkestColorString,
         }, ContrastLevelName.SmallBodyText, 'darkest', lightnessProxies), `Failed to find dark mode on-self foreground color for ${firstColor.colorName}`);
+        /**
+         * Reversed palette order for dark mode on-self backgrounds. `findColorAtContrastLevel`
+         * picks the last qualifying color in array order. With the natural lightest-to-darkest
+         * order, high-contrast backgrounds end up as the darkest palette colors, which are
+         * indistinguishable from the dark page background. Reversing the order makes it select
+         * the lightest palette color that still achieves the required contrast level, producing
+         * backgrounds that are visible against the dark page.
+         */
+        const reversedColorStrings = colorStrings.toReversed();
         // Pre-compute base name parts that don't change per cross
         const baseNameParts = [
             prefix,
@@ -215,7 +278,7 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
                     : cross.crossWith === 'color-on-self-dark-mode'
                         ? {
                             foreground: darkSelfFgString,
-                            background: colorStrings,
+                            background: reversedColorStrings,
                         }
                         : cross.crossWith === 'color-on-self-light-mode'
                             ? {
@@ -285,7 +348,15 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
             if (!comparison) {
                 throw new Error(`Forgot to handle crossWith: '${cross.crossWith}'`);
             }
-            const matchedColorString = findColorAtContrastLevel(comparison, cross.contrast);
+            const matchedColorString = cross.contrast === ExtremeContrastLevel.HighestContrast ||
+                cross.contrast === ExtremeContrastLevel.LowestContrast
+                ? resolveExtremeContrastColor({
+                    comparison,
+                    isHighestContrast: cross.contrast === ExtremeContrastLevel.HighestContrast,
+                    lightestColorString,
+                    darkestColorString,
+                })
+                : findColorAtContrastLevel(comparison, cross.contrast);
             const matchedColor = matchedColorString
                 ? colorByDefault[matchedColorString]
                 : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "theme-vir",
-    "version": "28.24.0",
+    "version": "28.25.0",
     "description": "Create an entire web theme.",
     "keywords": [
         "design",