theme-vir 28.23.1 → 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/dist/color-theme/color-palette-book-pages.d.ts

@@ -8,10 +8,10 @@ import { type BuildLowLevelColorThemeOptions, type ColorPaletteVars } from './bu
  * @see `createColorThemeBookPages` for creating full color theme pages.
  */
 export declare function createColorPaletteBookPages({ colors, parent, title, includeContrast, includeTheme, useVerticalTheme, options, }: {
-    parent: Readonly<BookPage>;
     title: string;
     colors: Readonly<ColorPaletteVars>;
 } & PartialWithUndefined<{
+    parent: Readonly<BookPage>;
     includeContrast: boolean;
     includeTheme: boolean;
     useVerticalTheme: boolean;

package/dist/color-theme/color-palette-book-pages.js

@@ -1,7 +1,7 @@
 import { check } from '@augment-vir/assert';
 import { VirColorPair } from '@electrovir/color';
 import { defineBookPage } from 'element-book';
-import { css, html, unsafeCSS } from 'element-vir';
+import { css, html, listen, unsafeCSS } from 'element-vir';
 import { noNativeSpacing, viraTheme } from 'vira';
 import { buildColorTheme, groupColors, } from './build-color-theme.js';
 import { createColorThemeBookPages } from './color-theme-book-pages.js';
@@ -64,59 +64,94 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
         parent: topColorsPage,
         title: 'Palette',
         defineExamples({ defineExample }) {
-            Object.entries(colorGroups).forEach(([groupName, colors,]) => {
-                defineExample({
-                    title: groupName,
-                    styles: css `
-                            :host {
-                                display: flex;
-                                flex-direction: column;
-                            }
+            defineExample({
+                title: 'All Colors',
+                styles: css `
+                    :host {
+                        display: flex;
+                        flex-direction: row;
+                    }
 
-                            .swatch-wrapper {
-                                display: flex;
-                                gap: 4px;
-                                align-items: center;
+                    p {
+                        ${noNativeSpacing}
+                    }
 
-                                & .swatch {
-                                    width: 50px;
-                                    height: 50px;
-                                }
+                    .color-column {
+                        display: flex;
+                        flex-direction: column;
+                    }
 
-                                & .color-details {
-                                    font-family: monospace;
-                                    font-size: 12px;
-                                    color: ${viraTheme.colors['vira-grey-foreground-header']
-                        .foreground.value};
-                                }
+                    .column-title {
+                        text-align: center;
+                        font-size: 12px;
+                        padding-bottom: 4px;
+                        border-bottom: 1px solid
+                            ${viraTheme.colors['vira-grey-foreground-decoration'].foreground.value};
+                        margin-bottom: 4px;
+                        color: ${viraTheme.colors['vira-grey-foreground-non-body'].foreground
+                    .value};
+                    }
 
-                                & .color-value {
-                                    margin-left: 1ch;
-                                }
-                            }
-                        `,
-                    render() {
-                        return colors.map((color) => {
+                    .swatch-wrapper {
+                        display: flex;
+                        gap: 4px;
+                        align-items: center;
+
+                        & .swatch {
+                            width: 50px;
+                            height: 50px;
+                            cursor: pointer;
+                        }
+
+                        & .color-details {
+                            display: none;
+                            font-family: monospace;
+                            font-size: 12px;
+                            color: ${viraTheme.colors['vira-grey-foreground-non-body'].foreground
+                    .value};
+                        }
+
+                        &.expanded .color-details {
+                            display: block;
+                        }
+
+                        & .color-value {
+                            margin-left: 1ch;
+                        }
+                    }
+                `,
+                render() {
+                    return Object.entries(colorGroups).map(([groupName, colors,]) => {
+                        return html `
+                                <div class="color-column">
+                                    <p class="column-title">${groupName}</p>
+                                    ${colors.map((color) => {
                             return html `
-                                    <div class="swatch-wrapper">
-                                        <div
-                                            class="swatch"
-                                            style=${css `
-                                                background-color: ${unsafeCSS(color.definition.default)};
-                                            `}
-                                        ></div>
-                                        <p class="color-details">
-                                            <span>${color.cssVarName}</span>
-                                            <br />
-                                            <span class="color-value">
-                                                ${color.definition.default}
-                                            </span>
-                                        </p>
-                                    </div>
-                                `;
-                        });
-                    },
-                });
+                                            <div class="swatch-wrapper">
+                                                <div
+                                                    class="swatch"
+                                                    style=${css `
+                                                        background-color: ${unsafeCSS(color.definition.default)};
+                                                    `}
+                                                    ${listen('click', (event) => {
+                                const wrapper = event.currentTarget.parentElement;
+                                wrapper?.classList.toggle('expanded');
+                            })}
+                                                ></div>
+                                                <p class="color-details">
+                                                    <span>${color.cssVarName}</span>
+                                                    <br />
+                                                    <span class="color-value">
+                                                        ${color.definition.default}
+                                                    </span>
+                                                </p>
+                                            </div>
+                                        `;
+                        })}
+                                </div>
+                            `;
+                    });
+                },
             });
         },
     });
@@ -214,24 +249,25 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
             };
         }));
     }
-    const generatedTheme = buildColorTheme(colors, options);
+    function createThemePages() {
+        const generatedTheme = buildColorTheme(colors, options);
+        return createColorThemeBookPages({
+            parent: topColorsPage,
+            title: 'Theme (auto)',
+            theme: generatedTheme.defaultLight,
+            hideInverseColors: true,
+            useVerticalLayout: useVerticalTheme,
+            prefixGroupByCount: 2,
+            overrides: [generatedTheme.darkOverride],
+        });
+    }
     return [
         topColorsPage,
         colorPalettePage,
-        contrastsPage,
+        includeContrast ? contrastsPage : undefined,
         includeContrast ? blackWhiteContrastPage : undefined,
         includeContrast ? createSelfContrastPage(400) : undefined,
         includeContrast ? createSelfContrastPage(700) : undefined,
-        ...(includeTheme
-            ? createColorThemeBookPages({
-                parent: topColorsPage,
-                title: 'Theme (auto)',
-                theme: generatedTheme.defaultLight,
-                hideInverseColors: true,
-                useVerticalLayout: useVerticalTheme,
-                prefixGroupByCount: 2,
-                overrides: [generatedTheme.darkOverride],
-            })
-            : []),
+        ...(includeTheme ? createThemePages() : []),
     ].filter(check.isTruthy);
 }

package/package.json

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