theme-vir 28.18.7 → 28.20.0

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

@@ -0,0 +1,31 @@
+import { type ColorThemeOverride } from './color-theme-init.js';
+import { type ColorTheme } from './color-theme.js';
+/**
+ * Create the `<style>` id used to apply color themes globally by {@link applyGlobalColorTheme}.
+ *
+ * @category Internal
+ */
+export declare function createGlobalThemeStyleId(colorTheme: Readonly<ColorTheme>): string;
+/**
+ * Create the global `<style>` element used by {@link applyGlobalColorTheme} to apply a color theme.
+ *
+ * @category Internal
+ */
+export declare function createGlobalThemeStyleElement(colorTheme: Readonly<ColorTheme>, context?: Element): HTMLStyleElement;
+/**
+ * Sets all of a color theme's CSS vars in a global style element. If no override is given, the
+ * theme color default values are assigned.
+ *
+ * @category Color Theme
+ */
+export declare function applyGlobalColorTheme(fullTheme: ColorTheme, themeOverride?: ColorThemeOverride | undefined): void;
+/**
+ * A very inefficient way of setting all of a color theme's CSS vars on a given element. If no
+ * override is given, the theme color default values are assigned.
+ *
+ * @deprecated Use {@link applyGlobalColorTheme} instead whenever possible.
+ * @category Internal
+ */
+export declare function applyColorTheme(
+/** This should usually be the top-level `html` element. */
+element: HTMLElement, fullTheme: ColorTheme, themeOverride?: ColorThemeOverride | undefined): void;

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

@@ -0,0 +1,94 @@
+import { camelCaseToKebabCase, getObjectTypedValues } from '@augment-vir/common';
+import { setCssVarValue } from 'lit-css-vars';
+/**
+ * Create the `<style>` id used to apply color themes globally by {@link applyGlobalColorTheme}.
+ *
+ * @category Internal
+ */
+export function createGlobalThemeStyleId(colorTheme) {
+    return [
+        camelCaseToKebabCase(colorTheme.prefix),
+        'global-theme-vir-style',
+    ].join('-');
+}
+/**
+ * Create the global `<style>` element used by {@link applyGlobalColorTheme} to apply a color theme.
+ *
+ * @category Internal
+ */
+export function createGlobalThemeStyleElement(colorTheme, context = document.head) {
+    const styleId = createGlobalThemeStyleId(colorTheme);
+    const existingElement = context.querySelector(`style#${styleId}`);
+    if (existingElement instanceof HTMLStyleElement) {
+        return existingElement;
+    }
+    else {
+        const newStyleElement = globalThis.document.createElement('style');
+        newStyleElement.id = styleId;
+        context.append(newStyleElement);
+        return newStyleElement;
+    }
+}
+/**
+ * Sets all of a color theme's CSS vars in a global style element. If no override is given, the
+ * theme color default values are assigned.
+ *
+ * @category Color Theme
+ */
+export function applyGlobalColorTheme(fullTheme, themeOverride) {
+    const styleElement = createGlobalThemeStyleElement(fullTheme);
+    const cssVarDeclarations = getObjectTypedValues(fullTheme.colors).flatMap((themeColor) => {
+        return [
+            buildCssVarDeclaration({
+                layerKey: 'background',
+                themeColor,
+                themeOverride,
+            }),
+            buildCssVarDeclaration({
+                layerKey: 'foreground',
+                themeColor,
+                themeOverride,
+            }),
+        ];
+    });
+    styleElement.textContent = `:root {\n    ${cssVarDeclarations.join('\n    ')}\n}`;
+}
+/**
+ * A very inefficient way of setting all of a color theme's CSS vars on a given element. If no
+ * override is given, the theme color default values are assigned.
+ *
+ * @deprecated Use {@link applyGlobalColorTheme} instead whenever possible.
+ * @category Internal
+ */
+export function applyColorTheme(
+/** This should usually be the top-level `html` element. */
+element, fullTheme, themeOverride) {
+    getObjectTypedValues(fullTheme.colors).forEach((themeColor) => {
+        applyIndividualThemeColorValue({
+            element,
+            layerKey: 'background',
+            themeColor,
+            themeOverride,
+        });
+        applyIndividualThemeColorValue({
+            element,
+            layerKey: 'foreground',
+            themeColor,
+            themeOverride,
+        });
+    });
+}
+function buildCssVarDeclaration({ layerKey, themeOverride, themeColor, }) {
+    const override = themeOverride?.overrides[String(themeColor[layerKey].name)];
+    const value = override || themeColor[layerKey].default;
+    return `${themeColor[layerKey].name}: ${value};`;
+}
+function applyIndividualThemeColorValue({ element, layerKey, themeOverride, themeColor, }) {
+    const override = themeOverride?.overrides[String(themeColor[layerKey].name)];
+    const value = override || themeColor[layerKey].default;
+    setCssVarValue({
+        forCssVar: themeColor[layerKey],
+        onElement: element,
+        toValue: value,
+    });
+}

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

@@ -111,11 +111,13 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
     const allCrosses = crossProduct({
         crossWith: [
             'color-in-foreground-light-mode',
-            'color-in-background-light-mode',
             'color-in-foreground-dark-mode',
-            'color-in-background-dark-mode',
-            'color-on-self-dark-mode',
+            'color-behind-bg-light-mode',
+            'color-behind-bg-dark-mode',
+            'color-behind-fg-light-mode',
+            'color-behind-fg-dark-mode',
             'color-on-self-light-mode',
+            'color-on-self-dark-mode',
         ],
         contrast: contrastLevels,
     });
@@ -130,8 +132,10 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
             key: color.definition.default,
             value: color,
         }));
-        const lightestSelf = findClosestColor('white', colorStrings);
-        const darkestSelf = findClosestColor('black', colorStrings);
+        const lightestSelfString = findClosestColor('white', colorStrings);
+        const darkestSelfString = findClosestColor('black', colorStrings);
+        const lightestSelf = colorByDefault[lightestSelfString];
+        const darkestSelf = colorByDefault[darkestSelfString];
         // Pre-compute base name parts that don't change per cross
         const baseNameParts = [
             prefix,
@@ -143,33 +147,43 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
                     foreground: colorStrings,
                     background: defaultBackgroundString,
                 }
-                : cross.crossWith === 'color-in-background-light-mode'
+                : cross.crossWith === 'color-in-foreground-dark-mode'
                     ? {
-                        foreground: defaultBackgroundString,
-                        background: colorStrings,
+                        foreground: colorStrings,
+                        background: defaultForegroundString,
                     }
-                    : cross.crossWith === 'color-in-foreground-dark-mode'
+                    : cross.crossWith === 'color-on-self-dark-mode'
                         ? {
                             foreground: colorStrings,
-                            background: defaultForegroundString,
+                            background: darkestSelfString,
                         }
-                        : cross.crossWith === 'color-in-background-dark-mode'
+                        : cross.crossWith === 'color-on-self-light-mode'
                             ? {
-                                foreground: defaultForegroundString,
-                                background: colorStrings,
+                                foreground: colorStrings,
+                                background: lightestSelfString,
                             }
-                            : cross.crossWith === 'color-on-self-dark-mode'
+                            : cross.crossWith === 'color-behind-bg-light-mode'
                                 ? {
-                                    foreground: colorStrings,
-                                    background: darkestSelf,
+                                    foreground: defaultBackgroundString,
+                                    background: colorStrings,
                                 }
-                                : // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-                                    cross.crossWith === 'color-on-self-light-mode'
+                                : cross.crossWith === 'color-behind-bg-dark-mode'
+                                    ? {
+                                        foreground: defaultForegroundString,
+                                        background: colorStrings,
+                                    }
+                                    : cross.crossWith === 'color-behind-fg-light-mode'
                                         ? {
-                                            foreground: colorStrings,
-                                            background: lightestSelf,
+                                            foreground: defaultForegroundString,
+                                            background: colorStrings,
                                         }
-                                        : undefined;
+                                        : // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                                            cross.crossWith === 'color-behind-fg-dark-mode'
+                                                ? {
+                                                    foreground: defaultBackgroundString,
+                                                    background: colorStrings,
+                                                }
+                                                : undefined;
             if (!comparison) {
                 throw new Error(`Forgot to handle crossWith: '${cross.crossWith}'`);
             }
@@ -181,8 +195,21 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
                 log.error(`No valid '${colorGroupName}' color cross found for: ${stringify(cross)} with ${stringify(colorStrings)}`);
                 return undefined;
             }
+            const isSelfContrast = cross.crossWith === 'color-on-self-light-mode' ||
+                cross.crossWith === 'color-on-self-dark-mode';
+            const isBehindBg = cross.crossWith === 'color-behind-bg-light-mode' ||
+                cross.crossWith === 'color-behind-bg-dark-mode';
+            const isBehindFg = cross.crossWith === 'color-behind-fg-light-mode' ||
+                cross.crossWith === 'color-behind-fg-dark-mode';
             const colorValue = mapObjectValues(comparison, (key, value) => {
                 if (check.isString(value)) {
+                    // For self-contrast modes, use the CSS var reference for the background
+                    if (isSelfContrast && key === 'background') {
+                        const selfColor = cross.crossWith === 'color-on-self-light-mode'
+                            ? lightestSelf
+                            : darkestSelf;
+                        return selfColor?.definition.value ?? value;
+                    }
                     return value;
                 }
                 else {
@@ -190,25 +217,31 @@ export function buildColorTheme(colorPalette, { omittedColorValues = defaultOmit
                 }
             });
             const isLightMode = cross.crossWith === 'color-in-foreground-light-mode' ||
-                cross.crossWith === 'color-in-background-light-mode' ||
-                cross.crossWith === 'color-on-self-light-mode';
-            const isSelfContrast = cross.crossWith === 'color-on-self-light-mode' ||
-                cross.crossWith === 'color-on-self-dark-mode';
+                cross.crossWith === 'color-on-self-light-mode' ||
+                cross.crossWith === 'color-behind-bg-light-mode' ||
+                cross.crossWith === 'color-behind-fg-light-mode';
             const nameSuffix = isSelfContrast
                 ? [
                     'on',
                     'self',
                     cross.contrast,
                 ]
-                : cross.crossWith.includes('foreground')
+                : isBehindBg
                     ? [
-                        'foreground',
+                        'behind',
+                        'bg',
                         cross.contrast,
                     ]
-                    : [
-                        'background',
-                        cross.contrast,
-                    ];
+                    : isBehindFg
+                        ? [
+                            'behind',
+                            'fg',
+                            cross.contrast,
+                        ]
+                        : [
+                            'foreground',
+                            cross.contrast,
+                        ];
             const name = [
                 ...baseNameParts,
                 ...nameSuffix,

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

@@ -2,7 +2,7 @@ import { type RequiredAndNotNull, type Values } from '@augment-vir/common';
 import { CSSResult } from 'element-vir';
 import { type CssVarName, type SingleCssVarDefinition } from 'lit-css-vars';
 import { type RequireAtLeastOne } from 'type-fest';
-import { type ColorInit, type ColorInitReference, type ColorInitValue, type ColorThemeInit, type ColorThemeOverride } from './color-theme-init.js';
+import { type ColorInit, type ColorInitReference, type ColorInitValue, type ColorThemeInit } from './color-theme-init.js';
 /**
  * Same as {@link ColorInit} but without references.
  *
@@ -40,6 +40,7 @@ export type ColorTheme<Init extends ColorThemeInit = ColorThemeInit> = {
         colors: Init;
         default: Readonly<DefaultColorThemeInit>;
     };
+    prefix: string;
 };
 /**
  * All colors within a {@link ColorTheme}.
@@ -74,15 +75,6 @@ export type DefaultColorThemeInit = RequiredAndNotNull<NoRefColorInit> & {
  * @category Internal
  */
 export declare const themeDefaultKey = "theme-default";
-/**
- * Set all color theme CSS vars on the given element. If no override is given, the theme color
- * default values are assigned.
- *
- * @category Color Theme
- */
-export declare function applyColorTheme<const Theme extends ColorTheme>(
-/** This should usually be the top-level `html` element. */
-element: HTMLElement, fullTheme: Theme, themeOverride?: ColorThemeOverride | undefined): void;
 /**
  * Define a color theme.
  *

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

@@ -1,7 +1,7 @@
 import { assert, check } from '@augment-vir/assert';
-import { getObjectTypedEntries, getObjectTypedValues, log, } from '@augment-vir/common';
+import { getObjectTypedEntries, log, } from '@augment-vir/common';
 import { CSSResult } from 'element-vir';
-import { defineCssVars, setCssVarValue, } from 'lit-css-vars';
+import { defineCssVars, } from 'lit-css-vars';
 /** @category Internal */
 export function noRefColorInitToString(init) {
     if (check.isPrimitive(init) || init instanceof CSSResult) {
@@ -57,39 +57,6 @@ export function createColorCssVarDefault(fromName, init, defaultInit, colorsInit
  * @category Internal
  */
 export const themeDefaultKey = 'theme-default';
-/**
- * Set all color theme CSS vars on the given element. If no override is given, the theme color
- * default values are assigned.
- *
- * @category Color Theme
- */
-export function applyColorTheme(
-/** This should usually be the top-level `html` element. */
-element, fullTheme, themeOverride) {
-    getObjectTypedValues(fullTheme.colors).forEach((themeColor) => {
-        applyIndividualThemeColorValue({
-            element,
-            layerKey: 'background',
-            themeColor,
-            themeOverride,
-        });
-        applyIndividualThemeColorValue({
-            element,
-            layerKey: 'foreground',
-            themeColor,
-            themeOverride,
-        });
-    });
-}
-function applyIndividualThemeColorValue({ element, layerKey, themeOverride, themeColor, }) {
-    const override = themeOverride?.overrides[String(themeColor[layerKey].name)];
-    const value = override || themeColor[layerKey].default;
-    setCssVarValue({
-        forCssVar: themeColor[layerKey],
-        onElement: element,
-        toValue: value,
-    });
-}
 /**
  * Define a color theme.
  *
@@ -193,6 +160,7 @@ export function defineColorTheme(defaultInit, allColorsInit) {
                 colors: allColorsInit,
                 default: defaultInit,
             },
+            prefix: defaultInit.prefix,
         };
     }
     catch (error) {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './color-theme/apply-color-theme.js';
 export * from './color-theme/build-color-theme.js';
 export * from './color-theme/color-palette-book-pages.js';
 export * from './color-theme/color-theme-book-pages.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './color-theme/apply-color-theme.js';
 export * from './color-theme/build-color-theme.js';
 export * from './color-theme/color-palette-book-pages.js';
 export * from './color-theme/color-theme-book-pages.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "theme-vir",
-    "version": "28.18.7",
+    "version": "28.20.0",
     "description": "Create an entire web theme.",
     "keywords": [
         "design",
@@ -43,15 +43,15 @@
         "test:update": "virmator test web update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.59.0",
-        "@augment-vir/common": "^31.59.0",
+        "@augment-vir/assert": "^31.59.2",
+        "@augment-vir/common": "^31.59.2",
         "@electrovir/color": "^1.7.8",
         "apca-w3": "^0.1.9",
         "lit-css-vars": "^3.4.0",
         "type-fest": "^5.4.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.59.0",
+        "@augment-vir/test": "^31.59.2",
         "@types/apca-w3": "^0.1.3",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
@@ -60,12 +60,12 @@
         "@web/test-runner-visual-regression": "^0.10.0",
         "element-book": "^26.16.0",
         "element-vir": "^26.14.3",
-        "esbuild": "^0.27.2",
+        "esbuild": "^0.27.3",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
         "typedoc": "^0.28.16",
         "typescript": "5.9.3",
-        "vira": "^29.2.0",
+        "vira": "^29.3.0",
         "vite": "^7.3.1",
         "vite-tsconfig-paths": "^6.0.5"
     },