theme-vir 28.14.0 → 28.15.0

package/README.md

@@ -1,5 +1,5 @@
 # theme-vir
 
-Easy-to-create, all-in-one theme generator with `element-vir`. WIP.
+Easy-to-create, all-in-one theme generator with [`element-vir`](https://npmjs.com/package/element-vir). WIP.
 
-Reference docs: https://electrovir.github.io/vira/theme-vir/docs
+Reference docs: https://electrovir.github.io/theme-vir

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

@@ -0,0 +1,85 @@
+import { type PartialWithUndefined, type RequiredAndNotNull } from '@augment-vir/common';
+import { type CssVarDefinitions, type SingleCssVarDefinition } from 'lit-css-vars';
+import { type NoRefColorInit } from './color-theme.js';
+import { ContrastLevelName } from './contrast.js';
+/** @category Internal */
+export type ColorPaletteVars = CssVarDefinitions<Record<`${string}-${string}-${number}`, any>>;
+/** @category Internal */
+export type PaletteColor = {
+    suffix: string | undefined;
+    prefix: string;
+    colorName: string;
+    definition: SingleCssVarDefinition;
+    cssVarName: string;
+};
+/** @category Internal */
+export type ColorGroups = Record<string, PaletteColor[]>;
+/**
+ * Black and white color values.
+ *
+ * @category Internal
+ */
+export declare const defaultOmittedColorGroupColorValues: string[];
+/** @category Internal */
+export declare function groupColors(colors: Readonly<ColorPaletteVars>, 
+/**
+ * Color values to omit from the grouping. Defaults to
+ * {@link defaultOmittedColorGroupColorValues}.
+ *
+ * @default defaultOmittedColorGroupColorValues
+ */
+omittedColorValues?: ReadonlyArray<string>): ColorGroups;
+/** @category Internal */
+export declare function extractPaletteColor(color: Readonly<SingleCssVarDefinition>): PaletteColor;
+/** @category Internal */
+export declare function extractParam<const T extends PropertyKey>(possibleParams: ReadonlyArray<PropertyKey> | Readonly<Record<PropertyKey, boolean>>, { mapFrom, mapTo, }: Readonly<PartialWithUndefined<{
+    mapTo: Record<string, T>;
+    mapFrom: Record<T, any>;
+}>>): T[];
+/** @category Internal */
+export type ArrayOrSelectParam<T extends PropertyKey> = ReadonlyArray<T> | Readonly<Partial<Record<T, boolean>>>;
+/** @category Internal */
+export declare const defaultLightThemePair: RequiredAndNotNull<NoRefColorInit>;
+/** @category Internal */
+export declare const defaultContrastLevels: Readonly<ArrayOrSelectParam<ContrastLevelName>>;
+/**
+ * Creates a color theme from a color palette.
+ *
+ * @category Color Theme
+ */
+export declare function buildLowLevelColorTheme(colorPalette: Readonly<ColorPaletteVars>, { defaultTheme, omittedColorValues, crossContrastLevels, }?: Readonly<PartialWithUndefined<{
+    /**
+     * The default theme colors for {@link defineColorTheme}. Defaults to
+     * {@link defaultLightThemePair}.
+     *
+     * @default defaultLightThemePair
+     */
+    defaultTheme: RequiredAndNotNull<NoRefColorInit>;
+    /**
+     * All font weights to cross colors with. Defaults to {@link defaultContrastLevels}.
+     *
+     * @default defaultContrastLevels
+     */
+    crossContrastLevels: Readonly<ArrayOrSelectParam<ContrastLevelName>>;
+    /**
+     * Color values to omit from the grouping. Defaults to
+     * {@link defaultOmittedColorGroupColorValues}.
+     *
+     * @default defaultOmittedColorGroupColorValues
+     */
+    omittedColorValues: ReadonlyArray<string>;
+}>>): import("./color-theme.js").ColorTheme<{
+    [k: string]: ((Required<Pick<{
+        foreground: import("./color-theme.js").ColorInitValue;
+        background: import("./color-theme.js").ColorInitValue;
+    }, "foreground">> & Partial<Pick<{
+        foreground: import("./color-theme.js").ColorInitValue;
+        background: import("./color-theme.js").ColorInitValue;
+    }, "background">>) | (Required<Pick<{
+        foreground: import("./color-theme.js").ColorInitValue;
+        background: import("./color-theme.js").ColorInitValue;
+    }, "background">> & Partial<Pick<{
+        foreground: import("./color-theme.js").ColorInitValue;
+        background: import("./color-theme.js").ColorInitValue;
+    }, "foreground">>)) & {};
+}>;

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

@@ -0,0 +1,183 @@
+import { assert, assertWrap, check } from '@augment-vir/assert';
+import { crossProduct, filterMap, getOrSet, log, mapObjectValues, removeDuplicates, stringify, } from '@augment-vir/common';
+import { defineColorTheme, noRefColorInitToString, } from './color-theme.js';
+import { contrastLevelLabel, ContrastLevelName, findClosestColor, findColorAtContrastLevel, } from './contrast.js';
+/**
+ * Black and white color values.
+ *
+ * @category Internal
+ */
+export const defaultOmittedColorGroupColorValues = [
+    '#000000',
+    '#ffffff',
+    '#000',
+    '#fff',
+    'white',
+    'black',
+];
+/** @category Internal */
+export function groupColors(colors, 
+/**
+ * Color values to omit from the grouping. Defaults to
+ * {@link defaultOmittedColorGroupColorValues}.
+ *
+ * @default defaultOmittedColorGroupColorValues
+ */
+omittedColorValues = defaultOmittedColorGroupColorValues) {
+    const colorGroups = {};
+    Object.values(colors).forEach((color) => {
+        if (omittedColorValues.includes(color.default)) {
+            return;
+        }
+        const paletteColor = extractPaletteColor(color);
+        getOrSet(colorGroups, paletteColor.colorName, () => []).push(paletteColor);
+    });
+    return colorGroups;
+}
+/** @category Internal */
+export function extractPaletteColor(color) {
+    const split = String(color.name).replace(/^-+/, '').split('-');
+    const suffix = split.length > 2 ? split.at(-1) : undefined;
+    const prefix = assertWrap.isTruthy(split[0]);
+    // eslint-disable-next-line sonarjs/argument-type
+    const colorName = split.slice(1, suffix ? -1 : undefined).join('-');
+    return {
+        suffix,
+        prefix,
+        colorName,
+        definition: color,
+        cssVarName: String(color.name),
+    };
+}
+/** @category Internal */
+export function extractParam(possibleParams, { mapFrom, mapTo, }) {
+    if (check.isArray(possibleParams)) {
+        return removeDuplicates(possibleParams.map((param) => {
+            if (mapFrom && check.isKeyOf(param, mapFrom)) {
+                return param;
+            }
+            else if (mapTo && check.isKeyOf(param, mapTo) && mapTo[param] != undefined) {
+                return mapTo[param];
+            }
+            else {
+                throw new Error(`Unknown font weight: ${String(param)}`);
+            }
+        }));
+    }
+    else {
+        return extractParam(filterMap(Object.entries(possibleParams), ([name, enabled,]) => {
+            if (enabled) {
+                /**
+                 * This cast is okay because the recursive case (handling an array) will
+                 * guard against bas names or weights.
+                 */
+                return name;
+            }
+            else {
+                return undefined;
+            }
+        }, check.isTruthy), {
+            mapTo,
+            mapFrom,
+        });
+    }
+}
+/** @category Internal */
+export const defaultLightThemePair = {
+    background: 'white',
+    foreground: 'black',
+};
+/** @category Internal */
+export const defaultContrastLevels = {
+    [ContrastLevelName.BodyText]: true,
+    [ContrastLevelName.Header]: true,
+    [ContrastLevelName.Placeholder]: true,
+    [ContrastLevelName.Decoration]: true,
+};
+/**
+ * Creates a color theme from a color palette.
+ *
+ * @category Color Theme
+ */
+export function buildLowLevelColorTheme(colorPalette, { defaultTheme = defaultLightThemePair, omittedColorValues = defaultOmittedColorGroupColorValues, crossContrastLevels = defaultContrastLevels, } = {}) {
+    const contrastLevels = extractParam(crossContrastLevels, {
+        mapFrom: contrastLevelLabel,
+    });
+    const colorGroups = groupColors(colorPalette, omittedColorValues);
+    const themeColors = Object.fromEntries(Object.entries(colorGroups).flatMap(([colorGroupName, colors,]) => {
+        assert.isLengthAtLeast(colors, 1);
+        const colorStrings = colors.map((color) => color.definition.default);
+        const allCrosses = crossProduct({
+            crossWith: [
+                'ahead-background',
+                'behind-background',
+                'ahead-foreground',
+                'behind-foreground',
+                'self-light-front',
+                'self-light-back',
+            ],
+            contrast: contrastLevels,
+            // fontWeight: fontWeights,
+        });
+        const firstColor = colors[0];
+        const defaultForegroundString = noRefColorInitToString(defaultTheme.foreground);
+        const defaultBackgroundString = noRefColorInitToString(defaultTheme.background);
+        const lightestSelf = findClosestColor('white', colorStrings);
+        return filterMap(allCrosses, (cross) => {
+            const crossName = [
+                firstColor.prefix,
+                firstColor.colorName,
+                cross.crossWith,
+                cross.contrast,
+                // cross.fontWeight,
+            ].join('-');
+            const comparison = cross.crossWith === 'ahead-background'
+                ? {
+                    foreground: colorStrings,
+                    background: defaultBackgroundString,
+                }
+                : cross.crossWith === 'behind-background'
+                    ? {
+                        foreground: defaultBackgroundString,
+                        background: colorStrings,
+                    }
+                    : cross.crossWith === 'ahead-foreground'
+                        ? {
+                            foreground: colorStrings,
+                            background: defaultForegroundString,
+                        }
+                        : cross.crossWith === 'behind-foreground'
+                            ? {
+                                foreground: defaultForegroundString,
+                                background: colorStrings,
+                            }
+                            : cross.crossWith === 'self-light-back'
+                                ? {
+                                    foreground: colorStrings,
+                                    background: lightestSelf,
+                                }
+                                : {
+                                    foreground: lightestSelf,
+                                    background: colorStrings,
+                                };
+            const matchedColorString = findColorAtContrastLevel(comparison, cross.contrast);
+            const matchedColor = colors.find((color) => color.definition.default === matchedColorString);
+            if (!matchedColor) {
+                log.error(`No valid '${colorGroupName}' color cross found for: ${stringify(cross)} with ${stringify(colorStrings)}`);
+                return undefined;
+            }
+            return [
+                crossName,
+                mapObjectValues(comparison, (key, value) => {
+                    if (check.isString(value)) {
+                        return value;
+                    }
+                    else {
+                        return matchedColor.definition.value;
+                    }
+                }),
+            ];
+        }, check.isTruthy);
+    }));
+    return defineColorTheme(defaultTheme, themeColors);
+}

package/dist/color/color-palette-book-pages.d.ts

@@ -1,16 +1,18 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type BookPage } from 'element-book';
-import { type CssVarDefinitions, type CssVarsSetup } from 'lit-css-vars';
+import { type ColorPaletteVars } from './build-color-theme.js';
 /**
  * Create multiple element-book pages to showcase a bunch of color CSS variables.
  *
  * @category Color Theme
  * @see `createColorThemeBookPages` for creating full color theme pages.
  */
-export declare function createColorPaletteBookPages({ colors, parent, title, includeContrast, }: {
+export declare function createColorPaletteBookPages({ colors, parent, title, includeContrast, includeTheme, useVerticalTheme, }: {
     parent: Readonly<BookPage>;
     title: string;
-    colors: CssVarDefinitions<CssVarsSetup>;
+    colors: Readonly<ColorPaletteVars>;
 } & PartialWithUndefined<{
     includeContrast: boolean;
-}>): (BookPage<{}, Readonly<BookPage>, {}> | BookPage<{}, BookPage<{}, Readonly<BookPage>, {}>, {}>)[];
+    includeTheme: boolean;
+    useVerticalTheme: boolean;
+}>): BookPage[];

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

@@ -1,8 +1,9 @@
 import { check } from '@augment-vir/assert';
-import { getOrSet } from '@augment-vir/common';
 import { defineBookPage } from 'element-book';
 import { css, html, unsafeCSS } from 'element-vir';
 import { noNativeSpacing, viraColorPalette } from 'vira';
+import { buildLowLevelColorTheme, groupColors, } from './build-color-theme.js';
+import { createColorThemeBookPages } from './color-theme-book-pages.js';
 import { ThemeVirColorExample } from './elements/theme-vir-color-example.element.js';
 const blackWhiteCells = [
     {
@@ -46,44 +47,21 @@ const blackWhiteCells = [
         background: viraColorPalette['vira-white'],
     },
 ];
-const omittedColors = [
-    '#000000',
-    '#ffffff',
-    '#000',
-    '#fff',
-    'white',
-    'black',
-];
 /**
  * Create multiple element-book pages to showcase a bunch of color CSS variables.
  *
  * @category Color Theme
  * @see `createColorThemeBookPages` for creating full color theme pages.
  */
-export function createColorPaletteBookPages({ colors, parent, title, includeContrast, }) {
-    const colorGroups = {};
-    Object.entries(colors).forEach(([key, color,]) => {
-        if (omittedColors.includes(color.default)) {
-            return;
-        }
-        // eslint-disable-next-line sonarjs/slow-regex
-        const groupName = key.replace(/-[\d-]+$/, '');
-        const suffix = key.replace(groupName, '').replace(/^-+/, '');
-        getOrSet(colorGroups, groupName, () => []).push({
-            key,
-            suffix,
-            value: color.default,
-            definition: color,
-            varName: String(color.name),
-        });
-    });
+export function createColorPaletteBookPages({ colors, parent, title, includeContrast, includeTheme, useVerticalTheme, }) {
+    const colorGroups = groupColors(colors);
     const topColorsPage = defineBookPage({
         parent,
         title,
     });
     const colorPalettePage = defineBookPage({
         parent: topColorsPage,
-        title: `${title} Palette`,
+        title: 'Palette',
         defineExamples({ defineExample }) {
             Object.entries(colorGroups).forEach(([groupName, colors,]) => {
                 defineExample({
@@ -122,13 +100,15 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
                                         <div
                                             class="swatch"
                                             style=${css `
-                                                background-color: ${unsafeCSS(color.value)};
+                                                background-color: ${unsafeCSS(color.definition.default)};
                                             `}
                                         ></div>
                                         <p class="color-details">
-                                            <span>${color.varName}</span>
+                                            <span>${color.cssVarName}</span>
                                             <br />
-                                            <span class="color-value">${color.value}</span>
+                                            <span class="color-value">
+                                                ${color.definition.default}
+                                            </span>
                                         </p>
                                     </div>
                                 `;
@@ -138,92 +118,19 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
             });
         },
     });
-    const blackWhiteContrastPage = defineBookPage({
+    const contrastsPage = defineBookPage({
         parent: topColorsPage,
-        title: `${title} Contrast Black White`,
-        defineExamples({ defineExample }) {
-            Object.entries(colorGroups).forEach(([groupName, colors,]) => {
-                defineExample({
-                    title: groupName,
-                    styles: css `
-                            :host {
-                                display: flex;
-                                flex-direction: column;
-                                gap: 24px;
-                            }
-
-                            p {
-                                ${noNativeSpacing}
-                            }
-
-                            .darkness-level {
-                                text-align: center;
-                                font-size: 12px;
-                                color: ${viraColorPalette['vira-grey-50'].value};
-                            }
-
-                            td {
-                                padding: 4px 0;
-                            }
-                        `,
-                    render() {
-                        const colorRowTemplates = colors.map((color) => {
-                            const cellTemplates = blackWhiteCells.map((cell) => {
-                                return html `
-                                        <td>
-                                            <p class="darkness-level">${color.suffix}</p>
-                                            <${ThemeVirColorExample.assign({
-                                    color: {
-                                        background: cell.background || color.definition,
-                                        foreground: cell.foreground || color.definition,
-                                    },
-                                    showVarValues: true,
-                                    showVarNames: false,
-                                    showContrast: true,
-                                    fontWeight: cell.fontWeight,
-                                })}></${ThemeVirColorExample}>
-                                        </td>
-                                    `;
-                            });
-                            return html `
-                                    <tr>${cellTemplates}</tr>
-                                `;
-                        });
-                        const headerCells = blackWhiteCells.map((cell) => {
-                            const layerText = cell.background ? 'in back' : 'in front';
-                            const title = [
-                                cell.title,
-                                `(${layerText})`,
-                                `(${cell.fontWeight})`,
-                            ].join(' ');
-                            return html `
-                                    <th>${title}</th>
-                                `;
-                        });
-                        return html `
-                                <table cellspacing="0" cellpadding="0">
-                                    <thead><tr>${headerCells}</tr></thead>
-                                    <tbody>${colorRowTemplates}</tbody>
-                                </table>
-                            `;
-                    },
-                });
-            });
-        },
+        title: 'Palette Contrast',
     });
-    function createSelfContrastPage(fontWeight) {
+    function createContrastPage(contrastPageTitle, contrastCellsInput) {
         return defineBookPage({
-            parent: topColorsPage,
-            title: `${title} Contrast Self ${fontWeight}`,
+            parent: contrastsPage,
+            title: `${title} ${contrastPageTitle}`,
             defineExamples({ defineExample }) {
                 Object.entries(colorGroups).forEach(([groupName, colors,]) => {
-                    const selfContrastCells = colors.map((color) => {
-                        return {
-                            fontWeight,
-                            title: color.suffix,
-                            foreground: color.definition,
-                        };
-                    });
+                    const contrastCells = check.isArray(contrastCellsInput)
+                        ? contrastCellsInput
+                        : contrastCellsInput(colors);
                     defineExample({
                         title: groupName,
                         styles: css `
@@ -244,12 +151,13 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
                                 }
 
                                 td {
-                                    padding: 4px 0;
+                                    padding: 4px;
+                                    min-width: 170px;
                                 }
                             `,
                         render() {
                             const colorRowTemplates = colors.map((color) => {
-                                const cellTemplates = selfContrastCells.map((cell) => {
+                                const cellTemplates = contrastCells.map((cell) => {
                                     return html `
                                             <td>
                                                 <p class="darkness-level">${color.suffix}</p>
@@ -270,7 +178,7 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
                                         <tr>${cellTemplates}</tr>
                                     `;
                             });
-                            const headerCells = selfContrastCells.map((cell) => {
+                            const headerCells = contrastCells.map((cell) => {
                                 const layerText = cell.background ? 'in back' : 'in front';
                                 const title = [
                                     cell.title,
@@ -293,11 +201,32 @@ export function createColorPaletteBookPages({ colors, parent, title, includeCont
             },
         });
     }
+    const blackWhiteContrastPage = createContrastPage('Contrast Black White', blackWhiteCells);
+    function createSelfContrastPage(fontWeight) {
+        return createContrastPage(`Contrast Self ${fontWeight}`, (colors) => colors.map((color) => {
+            return {
+                fontWeight,
+                title: color.suffix || '',
+                foreground: color.definition,
+            };
+        }));
+    }
     return [
         topColorsPage,
         colorPalettePage,
+        contrastsPage,
         includeContrast ? blackWhiteContrastPage : undefined,
         includeContrast ? createSelfContrastPage(400) : undefined,
         includeContrast ? createSelfContrastPage(700) : undefined,
+        ...(includeTheme
+            ? createColorThemeBookPages({
+                parent: topColorsPage,
+                title: 'Theme (auto)',
+                theme: buildLowLevelColorTheme(colors),
+                hideInverseColors: true,
+                useVerticalLayout: useVerticalTheme,
+                prefixGroupByCount: 2,
+            })
+            : []),
     ].filter(check.isTruthy);
 }

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

@@ -7,17 +7,24 @@ import { type ColorTheme } from './color-theme.js';
  *
  * @category Color Theme
  */
-export declare function createColorThemeBookPages({ parent, title, theme, hideInverseColors, overrides, }: {
+export declare function createColorThemeBookPages({ parent, title, theme, hideInverseColors, overrides, useVerticalLayout, prefixGroupByCount, }: {
     title: string;
     theme: Readonly<ColorTheme>;
 } & PartialWithUndefined<{
     parent: Readonly<BookPage>;
     hideInverseColors: boolean;
     overrides: ReadonlyArray<Readonly<ColorThemeOverride>>;
+    useVerticalLayout: boolean;
+    /**
+     * The number of CSS variable name prefixes to group colors by.
+     *
+     * @default 0
+     */
+    prefixGroupByCount: number;
 }>): (BookPage<{}, Readonly<BookPage> | undefined, {
-    readonly 'Show Var Names': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
-    readonly 'Show Contrast Tips': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
+    'Show Var Names': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
+    'Show Contrast Tips': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
 }> | BookPage<{}, BookPage<{}, Readonly<BookPage> | undefined, {
-    readonly 'Show Var Names': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
-    readonly 'Show Contrast Tips': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
+    'Show Var Names': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
+    'Show Contrast Tips': import("element-book").BookPageControlInit<BookPageControlType.Checkbox>;
 }>, {}>)[];