theme-vir 28.24.0 → 28.25.1

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,9 +90,56 @@ export const defaultLightThemePair = {
 };
 /** @category Internal */
 export const defaultContrastLevels = getEnumValues(ContrastLevelName);
-function findColorWithPreference(colors, desiredContrastLevel, preference, 
-/** Pre-computed contrast-against-white values per color string. Higher = darker. */
-lightnessProxies) {
+/**
+ * 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, lightnessProxies, }) {
     const minContrast = contrastLevelNameMap[desiredContrastLevel].min;
     const candidateColors = check.isArray(colors.foreground)
         ? colors.foreground
@@ -140,6 +187,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 +203,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);
@@ -160,10 +212,12 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
         const colorStrings = colors.map((color) => color.definition.default);
         const firstColor = colors[0];
         // Create an object for O(1) color lookup instead of O(n) find()
-        const colorByDefault = arrayToObject(colors, (color) => ({
-            key: color.definition.default,
-            value: color,
-        }));
+        const colorByDefault = arrayToObject(colors, (color) => {
+            return {
+                key: color.definition.default,
+                value: color,
+            };
+        });
         /** Pre-computed contrast-against-white per color. Higher value = darker shade. */
         const lightnessProxies = arrayToObject(colorStrings, (colorString) => {
             return {
@@ -185,17 +239,36 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
          * bg. Fixed across all on-self contrast levels.
          */
         const lightSelfFgString = assertWrap.isTruthy(findColorWithPreference({
-            foreground: colorStrings,
-            background: lightestColorString,
-        }, ContrastLevelName.SmallBodyText, 'lightest', lightnessProxies), `Failed to find light mode on-self foreground color for ${firstColor.colorName}`);
+            colors: {
+                foreground: colorStrings,
+                background: lightestColorString,
+            },
+            desiredContrastLevel: ContrastLevelName.SmallBodyText,
+            preference: 'lightest',
+            lightnessProxies,
+        }), `Failed to find light mode on-self foreground color for ${firstColor.colorName}`);
         /**
          * On-self dark mode: darkest fg achieving small-body contrast on the darkest palette
          * bg. Fixed across all on-self contrast levels.
          */
         const darkSelfFgString = assertWrap.isTruthy(findColorWithPreference({
-            foreground: colorStrings,
-            background: darkestColorString,
-        }, ContrastLevelName.SmallBodyText, 'darkest', lightnessProxies), `Failed to find dark mode on-self foreground color for ${firstColor.colorName}`);
+            colors: {
+                foreground: colorStrings,
+                background: darkestColorString,
+            },
+            desiredContrastLevel: ContrastLevelName.SmallBodyText,
+            preference: '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 +288,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 +358,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/dist/color-theme/color-theme-code.js

@@ -8,8 +8,18 @@ import { CSSResult } from 'element-vir';
  */
 export function generateThemeCode(theme, options) {
     const paletteVarName = options?.paletteVarName;
-    const defaultInitCode = colorInitToCode(theme.init.default, 1, undefined, paletteVarName);
-    const colorsInitCode = colorThemeInitToCode(theme.init.colors, 1, theme.init.default, paletteVarName);
+    const defaultInitCode = colorInitToCode({
+        colorInit: theme.init.default,
+        indentLevel: 1,
+        defaultInit: undefined,
+        paletteVarName,
+    });
+    const colorsInitCode = colorThemeInitToCode({
+        colorsInit: theme.init.colors,
+        indentLevel: 1,
+        defaultInit: theme.init.default,
+        paletteVarName,
+    });
     const themeCode = `export const theme = defineColorTheme(\n${defaultInitCode},\n${colorsInitCode},\n);`;
     const overridesCodes = (options?.overrides || []).map((override) => {
         return generateOverrideCode(override, paletteVarName);
@@ -63,6 +73,7 @@ function generateOverrideCode(override, paletteVarName) {
 function tab(level) {
     return '    '.repeat(level);
 }
+// eslint-disable-next-line @virmator/prefer-params-object
 function colorInitValuesEqual(a, b) {
     if (typeof a !== typeof b) {
         return false;
@@ -116,7 +127,7 @@ function colorInitValueToCode(value, indentLevel, paletteVarName) {
         return `'${value.default}'`;
     }
 }
-function colorInitToCode(colorInit, indentLevel, defaultInit, paletteVarName) {
+function colorInitToCode({ colorInit, indentLevel, defaultInit, paletteVarName, }) {
     const entries = [];
     if ('foreground' in colorInit &&
         (!defaultInit || !colorInitValuesEqual(colorInit.foreground, defaultInit.foreground)) &&
@@ -142,9 +153,14 @@ function colorInitToCode(colorInit, indentLevel, defaultInit, paletteVarName) {
     }
     return `${tab(indentLevel)}{\n${entries.join('\n')}\n${tab(indentLevel)}}`;
 }
-function colorThemeInitToCode(colorsInit, indentLevel, defaultInit, paletteVarName) {
+function colorThemeInitToCode({ colorsInit, indentLevel, defaultInit, paletteVarName, }) {
     const entries = getObjectTypedEntries(colorsInit).map(([colorName, colorInit,]) => {
-        return `${tab(indentLevel + 1)}'${colorName}': ${colorInitToCode(colorInit, indentLevel + 1, defaultInit, paletteVarName).trimStart()},`;
+        return `${tab(indentLevel + 1)}'${colorName}': ${colorInitToCode({
+            colorInit,
+            indentLevel: indentLevel + 1,
+            defaultInit,
+            paletteVarName,
+        }).trimStart()},`;
     });
     return `${tab(indentLevel)}{\n${entries.join('\n')}\n${tab(indentLevel)}}`;
 }

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

@@ -16,6 +16,7 @@ export function noRefColorInitToString(init) {
  *
  * @category Internal
  */
+// eslint-disable-next-line @virmator/prefer-params-object
 export function createColorCssVarDefault(fromName, init, defaultInit, colorsInit) {
     const defaultForegroundKey = `${defaultInit.prefix}-default-fg`;
     const defaultBackgroundKey = `${defaultInit.prefix}-default-bg`;

package/dist/create-theme/define-theme-elements.js

@@ -77,7 +77,13 @@ function defineHeadingElement(options) {
     const headingSelectors = unsafeCSS(getEnumValues(HeadingLevel).join(', '));
     return defineElement()({
         tagName: headingTag,
-        hostClasses: typedObjectFromEntries(getEnumValues(HeadingLevel).map((headingLevel) => {
+        hostClasses: typedObjectFromEntries(
+        /**
+         * `mapEnumToObject` cannot be used here: host class keys must be prefixed with the
+         * element's tag name, not the bare enum values.
+         */
+        // eslint-disable-next-line @virmator/prefer-map-enum-to-object
+        getEnumValues(HeadingLevel).map((headingLevel) => {
             return [
                 `${headingTag}-${headingLevel}`,
                 ({ inputs }) => inputs.headingLevel === headingLevel,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "theme-vir",
-    "version": "28.24.0",
+    "version": "28.25.1",
     "description": "Create an entire web theme.",
     "keywords": [
         "design",
@@ -22,7 +22,7 @@
         "type": "git",
         "url": "git+https://github.com/electrovir/theme-vir.git"
     },
-    "license": "(MIT or CC0 1.0)",
+    "license": "(MIT OR CC0-1.0)",
     "author": {
         "name": "electrovir",
         "url": "https://github.com/electrovir"
@@ -43,30 +43,30 @@
         "test:update": "virmator test web update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.67.1",
-        "@augment-vir/common": "^31.67.1",
-        "@electrovir/color": "^1.7.8",
+        "@augment-vir/assert": "^32.2.1",
+        "@augment-vir/common": "^32.2.1",
+        "@electrovir/color": "^1.7.11",
         "apca-w3": "^0.1.9",
-        "lit-css-vars": "^3.5.0",
-        "type-fest": "^5.4.4"
+        "lit-css-vars": "^3.6.3",
+        "type-fest": "^5.8.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.67.1",
+        "@augment-vir/test": "^32.2.1",
         "@types/apca-w3": "^0.1.3",
-        "@web/dev-server-esbuild": "^1.0.5",
-        "@web/test-runner": "^0.20.2",
-        "@web/test-runner-commands": "^0.9.0",
-        "@web/test-runner-playwright": "^0.11.1",
-        "@web/test-runner-visual-regression": "^0.10.0",
-        "element-book": "^26.17.0",
-        "element-vir": "^26.14.5",
-        "esbuild": "^0.27.3",
+        "@web/dev-server-esbuild": "^2.0.0",
+        "@web/test-runner": "^1.0.0",
+        "@web/test-runner-commands": "^1.0.1",
+        "@web/test-runner-playwright": "^1.0.0",
+        "@web/test-runner-visual-regression": "^1.0.1",
+        "element-book": "^26.17.3",
+        "element-vir": "^26.17.1",
+        "esbuild": "^0.28.1",
         "istanbul-smart-text-reporter": "^1.1.5",
-        "markdown-code-example-inserter": "^3.0.3",
-        "typedoc": "^0.28.17",
+        "markdown-code-example-inserter": "^3.0.6",
+        "typedoc": "^0.28.20",
         "typescript": "5.9.3",
-        "vira": "^30.6.0",
-        "vite": "^7.3.1",
+        "vira": "^31.28.1",
+        "vite": "^8.1.5",
         "vite-tsconfig-paths": "^6.1.1"
     },
     "peerDependencies": {