theme-vir 28.13.0 → 28.15.0

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

@@ -1,79 +1,99 @@
+import { check } from '@augment-vir/assert';
+import { groupArrayBy } from '@augment-vir/common';
 import { BookPageControlType, defineBookPage, definePageControl, } from 'element-book';
 import { css, html, listen, nothing } from 'element-vir';
+import { generateThemeCode } from './color-theme.js';
 import { ThemeVirColorExample } from './elements/theme-vir-color-example.element.js';
 /**
  * Create multiple element-book pages to showcase a theme its overrides (if any).
  *
  * @category Color Theme
  */
-export function createColorThemeBookPages({ parent, title, theme, hideInverseColors, overrides, }) {
+export function createColorThemeBookPages({ parent, title, theme, hideInverseColors, overrides, useVerticalLayout, prefixGroupByCount = 0, }) {
+    const themeControls = {
+        'Show Var Names': definePageControl({
+            controlType: BookPageControlType.Checkbox,
+            initValue: false,
+        }),
+        'Show Contrast Tips': definePageControl({
+            controlType: BookPageControlType.Checkbox,
+            initValue: true,
+        }),
+    };
     const themeParentPage = defineBookPage({
         parent,
         title,
-        controls: {
-            'Show Var Names': definePageControl({
-                controlType: BookPageControlType.Checkbox,
-                initValue: false,
-            }),
-            'Show Contrast Tips': definePageControl({
-                controlType: BookPageControlType.Checkbox,
-                initValue: true,
-            }),
-        },
+        controls: themeControls,
     });
-    function createThemePage(defineExample, theme) {
-        Object.values(theme.colors).forEach((themeColor) => {
+    function buildThemeColorTemplate({ controls, theme, themeColorName, }) {
+        const themeColor = check.isKeyOf(themeColorName, theme.colors)
+            ? theme.colors[themeColorName]
+            : undefined;
+        const inverseThemeColor = check.isKeyOf(themeColorName, theme.inverse)
+            ? theme.inverse[themeColorName]
+            : undefined;
+        if (!themeColor || !inverseThemeColor) {
+            throw new Error(`No theme color found by name '${themeColorName}'`);
+        }
+        const normalTemplate = html `
+            <${ThemeVirColorExample.assign({
+            color: themeColor,
+            showVarValues: true,
+            showVarNames: controls['Show Var Names'],
+            showContrast: controls['Show Contrast Tips'],
+            fontWeight: 400,
+        })}></${ThemeVirColorExample}>
+        `;
+        const inverseColor = hideInverseColors ? undefined : inverseThemeColor;
+        const inverseTemplate = inverseColor
+            ? html `
+                  <${ThemeVirColorExample.assign({
+                color: inverseColor,
+                showVarValues: false,
+                showVarNames: controls['Show Var Names'],
+                showContrast: controls['Show Contrast Tips'],
+                fontWeight: 400,
+            })}></${ThemeVirColorExample}>
+              `
+            : nothing;
+        return html `
+            <div class="with-inverse">${normalTemplate}${inverseTemplate}</div>
+        `;
+    }
+    function createThemePageExamples(defineExample, theme) {
+        const groups = groupArrayBy(Object.keys(theme.colors), (value) => {
+            if (prefixGroupByCount) {
+                return value.split('-').slice(0, prefixGroupByCount).join('-');
+            }
+            else {
+                return value;
+            }
+        });
+        Object.entries(groups).forEach(([groupName, group,]) => {
+            if (!group) {
+                return;
+            }
             defineExample({
-                title: themeColor.name,
+                title: groupName,
                 styles: css `
-                    :host {
-                        display: flex;
-                        flex-direction: column;
-                        gap: 4px;
-                    }
-                `,
-                state() {
-                    return {
-                        forceShowEverything: false,
-                    };
-                },
-                render({ controls, state, updateState }) {
-                    const normalTemplate = html `
-                        <${ThemeVirColorExample.assign({
-                        color: themeColor,
-                        showVarValues: true,
-                        showVarNames: controls['Show Var Names'] || state.forceShowEverything,
-                        showContrast: controls['Show Contrast Tips'] || state.forceShowEverything,
-                    })}
-                            ${listen(ThemeVirColorExample.events.toggleShowVars, () => {
-                        updateState({
-                            forceShowEverything: !state.forceShowEverything,
-                        });
-                    })}
-                        ></${ThemeVirColorExample}>
-                    `;
-                    const inverseColor = hideInverseColors
-                        ? undefined
-                        : theme.inverse[themeColor.name];
-                    const inverseTemplate = inverseColor
-                        ? html `
-                              <${ThemeVirColorExample.assign({
-                            color: inverseColor,
-                            showVarValues: false,
-                            showVarNames: controls['Show Var Names'] || state.forceShowEverything,
-                            showContrast: controls['Show Contrast Tips'] || state.forceShowEverything,
-                        })}
-                                  ${listen(ThemeVirColorExample.events.toggleShowVars, () => {
-                            updateState({
-                                forceShowEverything: !state.forceShowEverything,
-                            });
-                        })}
-                              ></${ThemeVirColorExample}>
-                          `
-                        : nothing;
-                    return html `
-                        ${normalTemplate}${inverseTemplate}
-                    `;
+                        :host {
+                            display: flex;
+                            flex-direction: column;
+                            gap: 4px;
+                        }
+
+                        .with-inverse {
+                            display: flex;
+                            flex-direction: column;
+                            gap: 4px;
+                        }
+                    `,
+                render({ controls }) {
+                    return group.map((entry) => buildThemeColorTemplate({
+                        controls,
+                        theme,
+                        themeColorName: entry,
+                    }));
                 },
             });
         });
@@ -85,17 +105,34 @@ export function createColorThemeBookPages({ parent, title, theme, hideInverseCol
         parent: themeParentPage,
         title: 'Default Theme',
         descriptionParagraphs,
+        useVerticalExamples: useVerticalLayout,
+        controls: {
+            copy: definePageControl({
+                controlType: BookPageControlType.Custom,
+                content: html `
+                    <button
+                        ${listen('click', async () => {
+                    const code = generateThemeCode(theme, 'viraColorPalette');
+                    await navigator.clipboard.writeText(code);
+                })}
+                    >
+                        Copy Code
+                    </button>
+                `,
+            }),
+        },
         defineExamples({ defineExample }) {
-            createThemePage(defineExample, theme);
+            createThemePageExamples(defineExample, theme);
         },
     });
     const overridePages = (overrides || []).map((override) => {
         return defineBookPage({
             parent: themeParentPage,
             title: override.name,
+            useVerticalExamples: useVerticalLayout,
             descriptionParagraphs,
             defineExamples({ defineExample }) {
-                createThemePage(defineExample, override.asTheme);
+                createThemePageExamples(defineExample, override.asTheme);
             },
         });
     });

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

@@ -1,4 +1,4 @@
-import { type RequiredAndNotNull } from '@augment-vir/common';
+import { type RequiredAndNotNull, type Values } from '@augment-vir/common';
 import { type CSSResult } from 'element-vir';
 import { type CssVarName, type SingleCssVarDefinition } from 'lit-css-vars';
 import { type RequireAtLeastOne } from 'type-fest';
@@ -10,13 +10,15 @@ import { type RequireAtLeastOne } from 'type-fest';
 export type ColorInitReference = RequireAtLeastOne<{
     refForeground: CssVarName;
     refBackground: CssVarName;
+    refDefaultBackground: true;
+    refDefaultForeground: true;
 }>;
 /**
  * All possible types for {@link ColorInit}.
  *
  * @category Internal
  */
-export type ColorInitValue = string | number | CSSResult | ColorInitReference;
+export type ColorInitValue = string | number | CSSResult | ColorInitReference | SingleCssVarDefinition;
 /**
  * An individual theme color init.
  *
@@ -80,12 +82,14 @@ export type AllColorThemeColors<Init extends ColorThemeInit = ColorThemeInit> =
 } & {
     [themeDefaultKey]: ColorThemeColor<RequiredAndNotNull<NoRefColorInit>, typeof themeDefaultKey>;
 };
+/** @category Internal */
+export declare function noRefColorInitToString(init: Values<NoRefColorInit>): string;
 /**
  * Handles a color init value.
  *
  * @category Internal
  */
-export declare function createColorCssVarDefault(fromName: string, init: ColorInitValue, defaultInit: RequiredAndNotNull<NoRefColorInit>, colorsInit: ColorThemeInit): Exclude<ColorInitValue, ColorInitReference>;
+export declare function createColorCssVarDefault(fromName: string, init: ColorInitValue, defaultInit: RequiredAndNotNull<NoRefColorInit>, colorsInit: ColorThemeInit): string | number | CSSResult;
 /**
  * Default foreground/background color theme used in {@link ColorTheme}. Do not define a theme color
  * with this name!
@@ -99,3 +103,9 @@ export declare const themeDefaultKey = "theme-default";
  * @category Color Theme
  */
 export declare function defineColorTheme<const Init extends ColorThemeInit>(defaultInit: RequiredAndNotNull<NoRefColorInit>, allColorsInit: Init): ColorTheme<Init>;
+/**
+ * Convert a color theme into code to define that color theme.
+ *
+ * @category Color Theme
+ */
+export declare function generateThemeCode(theme: ColorTheme, paletteVarName?: string | undefined): string;

package/dist/color/color-theme.js

@@ -1,21 +1,39 @@
 import { assert, check } from '@augment-vir/assert';
-import { getObjectTypedEntries, log } from '@augment-vir/common';
+import { getObjectTypedEntries, log, } from '@augment-vir/common';
 import { defineCssVars, } from 'lit-css-vars';
+/** @category Internal */
+export function noRefColorInitToString(init) {
+    if (check.isPrimitive(init) || '_$cssResult$' in init) {
+        return String(init);
+    }
+    else {
+        return init.default;
+    }
+}
 /**
  * Handles a color init value.
  *
  * @category Internal
  */
 export function createColorCssVarDefault(fromName, init, defaultInit, colorsInit) {
-    const referenceKey = check.hasKey(init, 'refBackground')
-        ? 'refBackground'
-        : check.hasKey(init, 'refForeground')
-            ? 'refForeground'
-            : undefined;
-    const reference = referenceKey && check.hasKey(init, referenceKey) ? init[referenceKey] : undefined;
-    if (reference) {
+    if (check.isPrimitive(init) || '_$cssResult$' in init) {
+        return init;
+    }
+    else if ('refDefaultBackground' in init) {
+        return '--var(default-bg)';
+    }
+    else if ('refDefaultForeground' in init) {
+        return '--var(default-fg)';
+    }
+    else if ('refBackground' in init || 'refForeground' in init) {
+        const referenceKey = check.hasKey(init, 'refBackground')
+            ? 'refBackground'
+            : check.hasKey(init, 'refForeground')
+                ? 'refForeground'
+                : undefined;
+        const reference = referenceKey && check.hasKey(init, referenceKey) ? init[referenceKey] : undefined;
         const layerKey = referenceKey === 'refBackground' ? 'background' : 'foreground';
-        const referenced = colorsInit[reference];
+        const referenced = reference && colorsInit[reference];
         if (!referenced) {
             throw new Error(`Color theme ${referenceKey} reference '${reference}' does not exist. (Referenced from '${fromName}'.)`);
         }
@@ -26,7 +44,7 @@ export function createColorCssVarDefault(fromName, init, defaultInit, colorsInit
         return `var(--${reference}-${layerKey === 'foreground' ? 'fg' : 'bg'}, ${createColorCssVarDefault(reference, colorValue, defaultInit, colorsInit)})`;
     }
     else {
-        return init;
+        return init.value;
     }
 }
 /**
@@ -157,3 +175,104 @@ function createCssVarNames(colorName) {
         ].join('-'),
     };
 }
+/**
+ * Convert a color theme into code to define that color theme.
+ *
+ * @category Color Theme
+ */
+export function generateThemeCode(theme, paletteVarName) {
+    const defaultInitCode = colorInitToCode(theme.init.default, 1, undefined, paletteVarName);
+    const colorsInitCode = colorThemeInitToCode(theme.init.colors, 1, theme.init.default, paletteVarName);
+    return `defineColorTheme(\n${defaultInitCode},\n${colorsInitCode},\n)`;
+}
+function tab(level) {
+    return '    '.repeat(level);
+}
+function colorInitValuesEqual(a, b) {
+    if (typeof a !== typeof b) {
+        return false;
+    }
+    if (typeof a === 'string' || typeof a === 'number') {
+        return a === b;
+    }
+    if ('_$cssResult$' in a && '_$cssResult$' in b) {
+        return a.cssText === b.cssText;
+    }
+    // For references and SingleCssVarDefinition, compare as JSON
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function extractCssVarName(cssValue) {
+    const match = cssValue.match(/^var\(--([^,)]+)/);
+    return match ? match[1] : undefined;
+}
+function colorInitValueToCode(value, indentLevel, paletteVarName) {
+    if (typeof value === 'string') {
+        return `'${value}'`;
+    }
+    else if (typeof value === 'number') {
+        return String(value);
+    }
+    else if ('_$cssResult$' in value) {
+        const cssText = String(value);
+        if (paletteVarName) {
+            const varName = extractCssVarName(cssText);
+            if (varName) {
+                return `${paletteVarName}['${varName}']`;
+            }
+        }
+        return `css\`${cssText}\``;
+    }
+    else if ('refBackground' in value ||
+        'refForeground' in value ||
+        'refDefaultBackground' in value ||
+        'refDefaultForeground' in value) {
+        const entries = [];
+        if ('refForeground' in value) {
+            entries.push(`${tab(indentLevel + 1)}refForeground: '${value.refForeground}',`);
+        }
+        if ('refBackground' in value) {
+            entries.push(`${tab(indentLevel + 1)}refBackground: '${value.refBackground}',`);
+        }
+        if ('refDefaultForeground' in value) {
+            entries.push(`${tab(indentLevel + 1)}refDefaultForeground: true,`);
+        }
+        if ('refDefaultBackground' in value) {
+            entries.push(`${tab(indentLevel + 1)}refDefaultBackground: true,`);
+        }
+        return `{\n${entries.join('\n')}\n${tab(indentLevel)}}`;
+    }
+    else {
+        // SingleCssVarDefinition
+        return `'${value.default}'`;
+    }
+}
+function colorInitToCode(colorInit, indentLevel, defaultInit, paletteVarName) {
+    const entries = [];
+    if ('foreground' in colorInit &&
+        (!defaultInit || !colorInitValuesEqual(colorInit.foreground, defaultInit.foreground))) {
+        // Check if foreground matches default background (use refDefaultBackground)
+        if (defaultInit && colorInitValuesEqual(colorInit.foreground, defaultInit.background)) {
+            entries.push(`${tab(indentLevel + 1)}foreground: {\n${tab(indentLevel + 2)}refDefaultBackground: true,\n${tab(indentLevel + 1)}},`);
+        }
+        else {
+            entries.push(`${tab(indentLevel + 1)}foreground: ${colorInitValueToCode(colorInit.foreground, indentLevel + 1, paletteVarName)},`);
+        }
+    }
+    if ('background' in colorInit &&
+        (!defaultInit || !colorInitValuesEqual(colorInit.background, defaultInit.background))) {
+        // Check if background matches default foreground (use refDefaultForeground)
+        if (defaultInit && colorInitValuesEqual(colorInit.background, defaultInit.foreground)) {
+            entries.push(`${tab(indentLevel + 1)}background: {\n${tab(indentLevel + 2)}refDefaultForeground: true,\n${tab(indentLevel + 1)}},`);
+        }
+        else {
+            entries.push(`${tab(indentLevel + 1)}background: ${colorInitValueToCode(colorInit.background, indentLevel + 1, paletteVarName)},`);
+        }
+    }
+    return `${tab(indentLevel)}{\n${entries.join('\n')}\n${tab(indentLevel)}}`;
+}
+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)}{\n${entries.join('\n')}\n${tab(indentLevel)}}`;
+}

package/dist/color/contrast.d.ts

@@ -1,17 +1,52 @@
-import { type ArrayElement } from '@augment-vir/common';
+import { type ArrayElement, type ExtractKeysWithMatchingValues, type Values } from '@augment-vir/common';
 /**
  * All font weights that font sizes are calculated for. Used in {@link FontSizes} and
  * {@link calculateFontSizes}.
  *
  * @category Internal
  */
-export type FontSizeWeights = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+export type FontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/**
+ * All considered font weights in {@link FontWeight} mapped by their weight name.
+ *
+ * @category Internal
+ */
+export declare const fontWeightByName: {
+    readonly Thin: 100;
+    readonly ExtraLight: 200;
+    readonly Light: 300;
+    readonly Normal: 400;
+    readonly Medium: 500;
+    readonly SemiBold: 600;
+    readonly Bold: 700;
+    readonly ExtraBold: 800;
+    readonly Heavy: 900;
+};
+/**
+ * All font weight names from {@link fontWeightByName}.
+ *
+ * @category Internal
+ */
+export type FontWeightName = keyof typeof fontWeightByName;
+/**
+ * All font weight names from {@link fontWeightByName}.
+ *
+ * @category Internal
+ */
+export declare const FontWeightName: { [Key in FontWeightName]: Key; };
+/**
+ * All considered font weights in {@link FontWeight} mapped to their weight name from
+ * {@link fontWeightByName}.
+ *
+ * @category Internal
+ */
+export declare const fontWeightToName: { [Weight in Values<typeof fontWeightByName>]: ExtractKeysWithMatchingValues<typeof fontWeightByName, Weight>; };
 /**
  * A mapping of font weights to font sizes. Used in {@link calculateFontSizes}.
  *
  * @category Internal
  */
-export type FontSizes = Record<FontSizeWeights, number>;
+export type FontSizes = Record<FontWeight, number>;
 /**
  * Contrast calculations produced by {@link calculateContrast}.
  *
@@ -41,6 +76,21 @@ export type ColorPair = {
  * @category Internal
  */
 export declare function calculateContrast({ background, foreground, }: Readonly<ColorPair>): CalculatedContrast;
+/** @category Internal */
+export declare function findClosestColor(baseColor: string, possibleColors: ReadonlyArray<string>): string;
+/**
+ * Find a color from an array that matches the desired contrast level.
+ *
+ * @category Internal
+ * @returns `undefined` if no color match is found.
+ */
+export declare function findColorAtContrastLevel(colors: Readonly<{
+    foreground: string;
+    background: string[];
+} | {
+    foreground: string[];
+    background: string;
+}>, desiredContrastLevel: ContrastLevelName): string | undefined;
 /**
  * Calculated needed font sizes for each font weight for the given color contrast.
  *
@@ -59,11 +109,11 @@ export declare function determineContrastLevel(contrast: number): ContrastLevel;
  * @category Internal
  */
 export declare enum ContrastLevelName {
-    SmallBodyText = "small-body-text",
-    BodyText = "body-text",
-    NonBodyText = "non-body-text",
-    LargeText = "large-text",
-    SpotText = "spot-text",
+    SmallBodyText = "small-body",
+    BodyText = "body",
+    NonBodyText = "non-body",
+    Header = "header",
+    Placeholder = "placeholder",
     Decoration = "decoration",
     Invisible = "invisible"
 }
@@ -78,7 +128,7 @@ export declare const contrastLevelLabel: Record<ContrastLevelName, string>;
  *
  * @category Internal
  */
-export declare const orderedContrastLevelNames: readonly [ContrastLevelName.SmallBodyText, ContrastLevelName.BodyText, ContrastLevelName.NonBodyText, ContrastLevelName.LargeText, ContrastLevelName.SpotText, ContrastLevelName.Decoration, ContrastLevelName.Invisible];
+export declare const orderedContrastLevelNames: readonly [ContrastLevelName.SmallBodyText, ContrastLevelName.BodyText, ContrastLevelName.NonBodyText, ContrastLevelName.Header, ContrastLevelName.Placeholder, ContrastLevelName.Decoration, ContrastLevelName.Invisible];
 /**
  * Color contrast level details.
  *
@@ -121,13 +171,13 @@ export declare const contrastLevels: readonly [{
     readonly apcaDescription: "The minimum level recommended for content text that is not body, column, or block text. In other words, text you want people to read. The minimums: no smaller than 48px/200, 36px/300, 24px normal weight (400), 21px/500, 18px/600, 16px/700 (bold). These values based on the reference font Helvetica. To use these sizes as body text, add Lc 15 to the minimum contrast.";
 }, {
     readonly min: 45;
-    readonly name: ContrastLevelName.LargeText;
+    readonly name: ContrastLevelName.Header;
     readonly description: "Okay for large or headline text.";
     readonly apcaName: "large & sub-fluent text";
     readonly apcaDescription: "The minimum for larger, heavier text (36px normal weight or 24px bold) such as headlines, and large text that should be fluently readable but is not body text. This is also the minimum for pictograms with fine details, or smaller outline icons, , no less than 4px in its smallest dimension.";
 }, {
     readonly min: 30;
-    readonly name: ContrastLevelName.SpotText;
+    readonly name: ContrastLevelName.Placeholder;
     readonly description: "Okay for disabled or placeholder text, copyright lines, icons, or non-text elements.";
     readonly apcaName: "spot & non text only";
     readonly apcaDescription: "The absolute minimum for any text not listed above, which means non-content text considered as \"spot readable\". This includes placeholder text and disabled element text, and some non-content like a copyright bug. This is also the minimum for large/solid semantic & understandable non-text elements such as \"mostly solid\" icons or pictograms, no less than 10px in its smallest dimension.";