theme-vir 28.13.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

@@ -0,0 +1,18 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type BookPage } from 'element-book';
+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, includeTheme, useVerticalTheme, }: {
+    parent: Readonly<BookPage>;
+    title: string;
+    colors: Readonly<ColorPaletteVars>;
+} & PartialWithUndefined<{
+    includeContrast: boolean;
+    includeTheme: boolean;
+    useVerticalTheme: boolean;
+}>): BookPage[];

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

@@ -0,0 +1,232 @@
+import { check } from '@augment-vir/assert';
+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 = [
+    {
+        title: 'Black',
+        fontWeight: 400,
+        foreground: viraColorPalette['vira-black'],
+    },
+    {
+        title: 'Black',
+        fontWeight: 700,
+        foreground: viraColorPalette['vira-black'],
+    },
+    {
+        title: 'White',
+        fontWeight: 400,
+        foreground: viraColorPalette['vira-white'],
+    },
+    {
+        title: 'White',
+        fontWeight: 700,
+        foreground: viraColorPalette['vira-white'],
+    },
+    {
+        title: 'Black',
+        fontWeight: 400,
+        background: viraColorPalette['vira-black'],
+    },
+    {
+        title: 'Black',
+        fontWeight: 700,
+        background: viraColorPalette['vira-black'],
+    },
+    {
+        title: 'White',
+        fontWeight: 400,
+        background: viraColorPalette['vira-white'],
+    },
+    {
+        title: 'White',
+        fontWeight: 700,
+        background: viraColorPalette['vira-white'],
+    },
+];
+/**
+ * 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, includeTheme, useVerticalTheme, }) {
+    const colorGroups = groupColors(colors);
+    const topColorsPage = defineBookPage({
+        parent,
+        title,
+    });
+    const colorPalettePage = defineBookPage({
+        parent: topColorsPage,
+        title: 'Palette',
+        defineExamples({ defineExample }) {
+            Object.entries(colorGroups).forEach(([groupName, colors,]) => {
+                defineExample({
+                    title: groupName,
+                    styles: css `
+                            :host {
+                                display: flex;
+                                flex-direction: column;
+                            }
+
+                            .swatch-wrapper {
+                                display: flex;
+                                gap: 4px;
+                                align-items: center;
+
+                                & .swatch {
+                                    width: 50px;
+                                    height: 50px;
+                                }
+
+                                & .color-details {
+                                    font-family: monospace;
+                                    font-size: 12px;
+                                    color: ${viraColorPalette['vira-grey-50'].value};
+                                }
+
+                                & .color-value {
+                                    margin-left: 1ch;
+                                }
+                            }
+                        `,
+                    render() {
+                        return 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>
+                                `;
+                        });
+                    },
+                });
+            });
+        },
+    });
+    const contrastsPage = defineBookPage({
+        parent: topColorsPage,
+        title: 'Palette Contrast',
+    });
+    function createContrastPage(contrastPageTitle, contrastCellsInput) {
+        return defineBookPage({
+            parent: contrastsPage,
+            title: `${title} ${contrastPageTitle}`,
+            defineExamples({ defineExample }) {
+                Object.entries(colorGroups).forEach(([groupName, colors,]) => {
+                    const contrastCells = check.isArray(contrastCellsInput)
+                        ? contrastCellsInput
+                        : contrastCellsInput(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;
+                                    min-width: 170px;
+                                }
+                            `,
+                        render() {
+                            const colorRowTemplates = colors.map((color) => {
+                                const cellTemplates = contrastCells.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 = contrastCells.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>
+                                `;
+                        },
+                    });
+                });
+            },
+        });
+    }
+    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>;
 }>, {}>)[];