@electrovir/color 0.0.0 → 1.1.0

package/dist/contrast/contrast.js

@@ -0,0 +1,254 @@
+import { assertWrap, check } from '@augment-vir/assert';
+import { arrayToObject, mapObjectValues, round, } from '@augment-vir/common';
+// @ts-expect-error: `fontLookupAPCA` is not in the types
+import { calcAPCA, fontLookupAPCA } from 'apca-w3';
+/**
+ * All considered font weights in {@link FontWeight} mapped by their weight name.
+ *
+ * @category Internal
+ */
+export const fontWeightByName = {
+    Thin: 100,
+    ExtraLight: 200,
+    Light: 300,
+    Normal: 400,
+    Medium: 500,
+    SemiBold: 600,
+    Bold: 700,
+    ExtraBold: 800,
+    Heavy: 900,
+};
+/**
+ * All font weight names from {@link fontWeightByName}.
+ *
+ * @category Internal
+ */
+export const FontWeightName = mapObjectValues(fontWeightByName, (key) => key);
+/**
+ * All considered font weights in {@link FontWeight} mapped to their weight name from
+ * {@link fontWeightByName}.
+ *
+ * @category Internal
+ */
+export const fontWeightToName = Object.fromEntries(Object.entries(fontWeightByName).map(([key, value,]) => [
+    value,
+    key,
+]));
+/**
+ * Calculate contrast for the given color combination.
+ *
+ * @category Internal
+ */
+export function calculateContrast({ background, foreground, }) {
+    const contrast = round(Number(calcAPCA(foreground, background)), { digits: 1 });
+    return {
+        contrast,
+        fontSizes: calculateFontSizes(contrast),
+        contrastLevel: determineContrastLevel(contrast),
+    };
+}
+/** @category Internal */
+export function findClosestColor(baseColor, possibleColors) {
+    return possibleColors.reduce((best, color) => {
+        const contrast = Math.abs(calculateContrast({
+            foreground: color,
+            background: baseColor,
+        }).contrast);
+        if (contrast > best.contrast) {
+            return best;
+        }
+        else {
+            return {
+                contrast,
+                color,
+            };
+        }
+    }, {
+        contrast: Infinity,
+        color: '',
+    }).color;
+}
+/**
+ * Find a color from an array that matches the desired contrast level.
+ *
+ * @category Internal
+ * @returns `undefined` if no color match is found.
+ */
+export function findColorAtContrastLevel(colors, desiredContrastLevel) {
+    const otherColors = check.isArray(colors.foreground)
+        ? colors.foreground
+        : check.isArray(colors.background)
+            ? colors.background
+            : new Error('No color array provided.');
+    if (otherColors instanceof Error) {
+        throw otherColors;
+    }
+    const desiredIndex = orderedContrastLevelNames.indexOf(desiredContrastLevel);
+    const bestMatch = otherColors.reduce((best, otherColor) => {
+        const contrast = calculateContrast({
+            foreground: check.isString(colors.foreground) ? colors.foreground : otherColor,
+            background: check.isString(colors.background) ? colors.background : otherColor,
+        });
+        const contrastIndex = orderedContrastLevelNames.indexOf(contrast.contrastLevel.name);
+        const distance = contrastIndex - desiredIndex;
+        if (distance > 0 || best.distance > distance) {
+            return best;
+        }
+        else {
+            return {
+                color: otherColor,
+                distance,
+            };
+        }
+    }, {
+        distance: 0,
+        color: undefined,
+    });
+    return bestMatch.color;
+}
+/**
+ * Calculated needed font sizes for each font weight for the given color contrast.
+ *
+ * @category Internal
+ */
+export function calculateFontSizes(contrast) {
+    const fontLookup = fontLookupAPCA(contrast).slice(1);
+    const sizes = arrayToObject(fontLookup, (value, index) => {
+        return {
+            key: (index + 1) * 100,
+            value,
+        };
+    });
+    return sizes;
+}
+/**
+ * Finds the color contrast level for the given contrast.
+ *
+ * @category Internal
+ */
+export function determineContrastLevel(contrast) {
+    return assertWrap.isDefined(contrastLevels.find((threshold) => threshold.min <= Math.abs(contrast)));
+}
+/**
+ * Names for each {@link ContrastLevel}.
+ *
+ * @category Internal
+ */
+export var ContrastLevelName;
+(function (ContrastLevelName) {
+    ContrastLevelName["SmallBodyText"] = "small-body";
+    ContrastLevelName["BodyText"] = "body";
+    ContrastLevelName["NonBodyText"] = "non-body";
+    ContrastLevelName["Header"] = "header";
+    ContrastLevelName["Placeholder"] = "placeholder";
+    ContrastLevelName["Decoration"] = "decoration";
+    ContrastLevelName["Invisible"] = "invisible";
+})(ContrastLevelName || (ContrastLevelName = {}));
+/**
+ * User-facing labels for {@link ContrastLevelName}.
+ *
+ * @category Internal
+ */
+export const contrastLevelLabel = {
+    [ContrastLevelName.SmallBodyText]: 'Small Text',
+    [ContrastLevelName.BodyText]: 'Body Text',
+    [ContrastLevelName.NonBodyText]: 'Non-body Text',
+    [ContrastLevelName.Header]: 'Header',
+    [ContrastLevelName.Placeholder]: 'Placeholder',
+    [ContrastLevelName.Decoration]: 'Decoration',
+    [ContrastLevelName.Invisible]: 'Invisible',
+};
+/**
+ * All {@link ContrastLevelName} values in order from highest contrast to lowest.
+ *
+ * @category Internal
+ */
+export const orderedContrastLevelNames = [
+    ContrastLevelName.SmallBodyText,
+    ContrastLevelName.BodyText,
+    ContrastLevelName.NonBodyText,
+    ContrastLevelName.Header,
+    ContrastLevelName.Placeholder,
+    ContrastLevelName.Decoration,
+    ContrastLevelName.Invisible,
+];
+/**
+ * All color contrast levels corresponding to APCA bronze guidelines.
+ *
+ * @category Internal
+ */
+export const contrastLevels = [
+    {
+        min: 90,
+        name: ContrastLevelName.SmallBodyText,
+        description: 'Perfect for all sizes of text, even small body text.',
+        apcaName: 'small body text only',
+        apcaDescription: 'Preferred level for fluent text and columns of body text with a font no smaller than 18px/weight 300 or 14px/weight 400 (normal), or non-body text with a font no smaller than 12px. Also a recommended minimum for extremely thin fonts with a minimum of 24px at weight 200. Lc 90 is a suggested maximum for very large and bold fonts (greater than 36px bold), and large areas of color.',
+    },
+    {
+        min: 75,
+        name: ContrastLevelName.BodyText,
+        description: 'Good for regular body text and anything larger.',
+        apcaName: 'body text okay',
+        apcaDescription: 'The minimum level for columns of body text with a font no smaller than 24px/300 weight, 18px/400, 16px/500 and 14px/700. This level may be used with non-body text with a font no smaller than 15px/400. Also, Lc 75 should be considered a minimum for larger for any larger text where readability is important.',
+    },
+    {
+        min: 60,
+        name: ContrastLevelName.NonBodyText,
+        description: 'Good for legible non-body text and anything larger.',
+        apcaName: 'fluent text only',
+        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.',
+    },
+    {
+        min: 45,
+        name: ContrastLevelName.Header,
+        description: 'Okay for large or headline text.',
+        apcaName: 'large & sub-fluent text',
+        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.',
+    },
+    {
+        min: 30,
+        name: ContrastLevelName.Placeholder,
+        description: 'Okay for disabled or placeholder text, copyright lines, icons, or non-text elements.',
+        apcaName: 'spot & non text only',
+        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.',
+    },
+    {
+        min: 15,
+        name: ContrastLevelName.Decoration,
+        description: 'Only okay for decorations like graphics, borders, dividers, etc. Do not use for any text.',
+        apcaName: 'no text usage',
+        apcaDescription: 'The absolute minimum for any non-text that needs to be discernible and differentiable, but does not apply to semantic non-text such as icons, and is no less than 15px in its smallest dimension. This may include dividers, and in some cases large buttons or thick focus visible outlines, but does not include fine details which have a higher minimum. Designers should treat anything below this level as invisible, as it will not be visible for many users. This minimum level should be avoided for any items important to the use, understanding, or interaction of the site.',
+    },
+    {
+        min: 0,
+        name: ContrastLevelName.Invisible,
+        description: 'Effectively invisible for users.',
+        apcaName: 'invisible',
+        apcaDescription: 'This should be treated as invisible.',
+    },
+];
+/**
+ * A mapping of all color contrast levels mins to their contrast levels. Generated from
+ * {@link contrastLevels}.
+ *
+ * @category Internal
+ */
+export const contrastLevelMinMap = arrayToObject(contrastLevels, (contrastLevel) => {
+    return {
+        key: contrastLevel.min,
+        value: contrastLevel,
+    };
+});
+/**
+ * A mapping of all color contrast levels mins to their contrast levels. Generated from
+ * {@link contrastLevels}.
+ *
+ * @category Internal
+ */
+export const contrastLevelNameMap = arrayToObject(contrastLevels, (contrastLevel) => {
+    return {
+        key: contrastLevel.name,
+        value: contrastLevel,
+    };
+});

package/dist/elements/vir-all-color-space-sliders.element.d.ts

@@ -0,0 +1,11 @@
+import { type Color } from '../color-class/color.js';
+/**
+ * Color sliders for all color spaces.
+ *
+ * @category Elements
+ */
+export declare const VirAllColorSpaceSliders: import("element-vir").DeclarativeElementDefinition<"vir-all-color-space-sliders", {
+    color: Readonly<Color>;
+}, {}, {
+    colorChange: import("element-vir").DefineEvent<string>;
+}, "vir-all-color-space-sliders-", "vir-all-color-space-sliders-", readonly [], readonly []>;

package/dist/elements/vir-all-color-space-sliders.element.js

@@ -0,0 +1,52 @@
+/* node:coverage disable */
+import { getObjectTypedKeys, getObjectTypedValues } from '@augment-vir/common';
+import { css, defineElement, defineElementEvent, html, listen } from 'element-vir';
+import { colorFormatsBySpace } from '../color-class/color-formats.js';
+import { VirColorFormatSliders } from './vir-color-format-sliders.element.js';
+/**
+ * Color sliders for all color spaces.
+ *
+ * @category Elements
+ */
+export const VirAllColorSpaceSliders = defineElement()({
+    tagName: 'vir-all-color-space-sliders',
+    styles: css `
+        :host {
+            display: flex;
+            flex-direction: column;
+            gap: 16px;
+        }
+
+        .color-space {
+            display: flex;
+            flex-wrap: wrap;
+            column-gap: 32px;
+            row-gap: 8px;
+        }
+    `,
+    events: {
+        colorChange: defineElementEvent(),
+    },
+    render({ inputs, dispatch, events }) {
+        const colorSpaceTemplates = getObjectTypedValues(colorFormatsBySpace).map((colorSpaceFormats) => {
+            const formatTemplates = getObjectTypedKeys(colorSpaceFormats).map((colorFormatName) => {
+                return html `
+                            <${VirColorFormatSliders.assign({
+                    color: inputs.color,
+                    colorFormatName,
+                })}
+                                ${listen(VirColorFormatSliders.events.colorChange, (event) => {
+                    dispatch(new events.colorChange(event.detail));
+                })}
+                            ></${VirColorFormatSliders}>
+                        `;
+            });
+            return html `
+                    <section class="color-space">${formatTemplates}</section>
+                `;
+        });
+        return html `
+            ${colorSpaceTemplates}
+        `;
+    },
+});

package/dist/elements/vir-color-format-sliders.element.d.ts

@@ -0,0 +1,13 @@
+import { type ColorFormatName } from '../color-class/color-formats.js';
+import { type Color } from '../color-class/color.js';
+/**
+ * Color sliders for all coordinates within a specific color format.
+ *
+ * @category Elements
+ */
+export declare const VirColorFormatSliders: import("element-vir").DeclarativeElementDefinition<"vir-color-format-sliders", {
+    color: Readonly<Color>;
+    colorFormatName: ColorFormatName;
+}, {}, {
+    colorChange: import("element-vir").DefineEvent<string>;
+}, "vir-color-format-sliders-", "vir-color-format-sliders-", readonly [], readonly []>;

package/dist/elements/vir-color-format-sliders.element.js

@@ -0,0 +1,54 @@
+/* node:coverage disable */
+import { getObjectTypedKeys } from '@augment-vir/common';
+import { css, defineElement, defineElementEvent, html, listen } from 'element-vir';
+import { noNativeSpacing } from 'vira';
+import { colorFormats, } from '../color-class/color-formats.js';
+import { VirColorSlider } from './vir-color-slider.element.js';
+/**
+ * Color sliders for all coordinates within a specific color format.
+ *
+ * @category Elements
+ */
+export const VirColorFormatSliders = defineElement()({
+    tagName: 'vir-color-format-sliders',
+    styles: css `
+        :host {
+            display: flex;
+            flex-direction: column;
+        }
+
+        h3 {
+            ${noNativeSpacing};
+        }
+    `,
+    events: {
+        colorChange: defineElementEvent(),
+    },
+    render({ inputs, dispatch, events }) {
+        const colorFormat = colorFormats[inputs.colorFormatName];
+        const coordinateTemplates = getObjectTypedKeys(colorFormat.coords).map((colorCoordinate) => {
+            return html `
+                    <${VirColorSlider.assign({
+                color: inputs.color,
+                colorCoordinateName: colorCoordinate,
+                colorFormatName: inputs.colorFormatName,
+            })}
+                        ${listen(VirColorSlider.events.valueChange, (event) => {
+                const newColor = inputs.color.clone();
+                newColor.set({
+                    [inputs.colorFormatName]: {
+                        [colorCoordinate]: event.detail,
+                    },
+                });
+                const newValue = newColor.toCss()[inputs.colorFormatName];
+                dispatch(new events.colorChange(newValue));
+            })}
+                    ></${VirColorSlider}>
+                `;
+        });
+        return html `
+            <h3>${inputs.colorFormatName}</h3>
+            ${coordinateTemplates}
+        `;
+    },
+});

package/dist/elements/vir-color-pair.element.d.ts

@@ -0,0 +1,23 @@
+import { type SingleCssVarDefinition } from 'lit-css-vars';
+import { type FontWeight } from '../contrast/contrast.js';
+/**
+ * A foreground/background color pair.
+ *
+ * @category Internal
+ */
+export type ColorPair = Record<'foreground' | 'background', SingleCssVarDefinition>;
+/**
+ * Showcase a foreground/backend color pair.
+ *
+ * @category Elements
+ */
+export declare const VirColorPair: import("element-vir").DeclarativeElementDefinition<"theme-vir-color-example", {
+    color: Readonly<ColorPair>;
+    showVarValues: boolean;
+    showVarNames: boolean;
+    showContrast: boolean;
+    fontWeight: FontWeight;
+}, {
+    previewElement: undefined | HTMLElement;
+    forceShowEverything: boolean;
+}, {}, "theme-vir-color-example-no-contrast-tips", "theme-vir-color-example-", readonly [], readonly []>;

package/dist/elements/vir-color-pair.element.js

@@ -0,0 +1,196 @@
+/* node:coverage disable */
+import { assertWrap, check } from '@augment-vir/assert';
+import { css, defineElement, html, listen, nothing, onDomCreated, unsafeCSS } from 'element-vir';
+import { noNativeFormStyles, noNativeSpacing } from 'vira';
+import { calculateContrast } from '../contrast/contrast.js';
+import { VirContrastIndicator } from './vir-contrast-indicator.element.js';
+/**
+ * Showcase a foreground/backend color pair.
+ *
+ * @category Elements
+ */
+export const VirColorPair = defineElement()({
+    tagName: 'theme-vir-color-example',
+    state() {
+        return {
+            previewElement: undefined,
+            forceShowEverything: false,
+        };
+    },
+    hostClasses: {
+        'theme-vir-color-example-no-contrast-tips': ({ inputs, state }) => !inputs.showContrast && !state.forceShowEverything,
+    },
+    styles: ({ hostClasses }) => css `
+        :host {
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            max-width: 100%;
+        }
+
+        .color-preview {
+            ${noNativeFormStyles};
+            cursor: pointer;
+            font-size: 32px;
+            padding-left: 12px;
+            padding-right: 0;
+            border: 1px solid #ccc;
+            border-radius: 8px;
+            display: flex;
+            gap: 8px;
+            align-items: baseline;
+
+            & b {
+                margin: 12px 0;
+                font-weight: bold;
+                text-decoration: underline;
+            }
+
+            & .square {
+                margin: 12px 0;
+                width: 24px;
+                height: 24px;
+                background-color: currentColor;
+            }
+        }
+        ${hostClasses['theme-vir-color-example-no-contrast-tips'].selector} {
+            & .needed-size-wrapper {
+                display: none;
+            }
+
+            & .color-preview {
+                padding: 4px 24px;
+            }
+        }
+
+        .needed-size-wrapper {
+            align-self: stretch;
+            width: 56px;
+            position: relative;
+            overflow: hidden;
+            border-left: 1px solid #ccc;
+        }
+
+        .needed-size {
+            top: 0;
+            height: 100%;
+            display: flex;
+            align-items: center;
+            left: 6px;
+            position: absolute;
+
+            & span {
+                margin: 0 auto;
+            }
+        }
+
+        .css-var-names {
+            font-family: monospace;
+            display: flex;
+            max-width: 100%;
+            flex-direction: column;
+            opacity: 0.6;
+            margin-top: 4px;
+        }
+
+        p {
+            ${noNativeSpacing};
+            display: flex;
+            gap: 0;
+            flex-wrap: wrap;
+
+            & span:last-child {
+                margin-left: 1ex;
+            }
+        }
+
+        ${VirContrastIndicator} {
+            margin-top: 1px;
+        }
+    `,
+    render({ state, updateState, inputs }) {
+        const colorRows = [
+            'foreground',
+            'background',
+        ].map((layerKey) => {
+            const keyString = [
+                inputs.color[layerKey].name,
+                inputs.showVarValues || state.forceShowEverything ? ':' : '',
+            ]
+                .filter(check.isTruthy)
+                .join('');
+            const valueTemplate = inputs.showVarValues || state.forceShowEverything
+                ? html `
+                          <span>${inputs.color[layerKey].default}</span>
+                      `
+                : nothing;
+            return html `
+                <p>
+                    <span>${keyString}</span>
+                    ${valueTemplate}
+                </p>
+            `;
+        });
+        const cssVarNamesTemplate = inputs.showVarNames || state.forceShowEverything
+            ? html `
+                      <div class="css-var-names">${colorRows}</div>
+                  `
+            : nothing;
+        const contrast = state.previewElement
+            ? calculateContrast({
+                foreground: globalThis
+                    .getComputedStyle(state.previewElement)
+                    .getPropertyValue('color'),
+                background: globalThis
+                    .getComputedStyle(state.previewElement)
+                    .getPropertyValue('background-color'),
+            })
+            : undefined;
+        const contrastTemplate = contrast && (inputs.showContrast || state.forceShowEverything)
+            ? html `
+                      <${VirContrastIndicator.assign({
+                contrast,
+                fontWeight: inputs.fontWeight,
+            })}></${VirContrastIndicator}>
+                  `
+            : nothing;
+        return html `
+            <button
+                ${listen('click', () => {
+            updateState({
+                forceShowEverything: !state.forceShowEverything,
+            });
+        })}
+                ${onDomCreated((element) => {
+            updateState({
+                previewElement: assertWrap.instanceOf(element, HTMLElement),
+            });
+        })}
+                class="color-preview"
+                style=${css `
+                    color: ${unsafeCSS(inputs.color.foreground.default)};
+                    background: ${unsafeCSS(inputs.color.background.default)};
+                `}
+            >
+                <div class="square"></div>
+                <b>Aa</b>
+                <div class="needed-size-wrapper">
+                    <span class="needed-size">
+                        <span
+                            style=${css `
+                                visibility: ${unsafeCSS((contrast?.fontSizes[400] || Infinity) > 150
+            ? 'hidden'
+            : 'visible')};
+                                font-weight: ${inputs.fontWeight};
+                                font-size: ${contrast ? contrast.fontSizes[400] : 14}px;
+                            `}
+                        >
+                            Min
+                        </span>
+                    </span>
+                </div>
+            </button>
+            ${contrastTemplate} ${cssVarNamesTemplate}
+        `;
+    },
+});

package/dist/elements/vir-color-slider.element.d.ts

@@ -0,0 +1,14 @@
+import { type ColorCoordinateName, type ColorFormatName } from '../color-class/color-formats.js';
+import { Color } from '../color-class/color.js';
+/**
+ * A slider for a specific color coordinate in a specific color space in a specific color.
+ *
+ * @category Elements
+ */
+export declare const VirColorSlider: import("element-vir").DeclarativeElementDefinition<"vir-color-slider", {
+    color: Readonly<Color>;
+    colorFormatName: ColorFormatName;
+    colorCoordinateName: ColorCoordinateName;
+}, {}, {
+    valueChange: import("element-vir").DefineEvent<number>;
+}, "vir-color-slider-", "vir-color-slider-gradient", readonly [], readonly []>;