@electrovir/color 0.0.0 → 1.1.0

package/dist/{color-formats.d.ts → color-class/color-formats.d.ts}

@@ -28,16 +28,6 @@ export type ColorCoordinateDefinition = {
     factor?: number | undefined;
     suffix?: string;
 }>;
-/**
- * A single color format definition.
- *
- * @category Internal
- */
-export type ColorFormatDefinition<ColorSpace extends string = string> = {
-    coords: Record<string, ColorCoordinateDefinition>;
-    /** This name for this color to be used in `Colorjs.to()`. Defaults to the color format key. */
-    colorSpace: ColorSpace;
-};
 /**
  * All raw supported color formats.
  *
@@ -184,15 +174,17 @@ export declare const rawColorFormats: {
     };
 };
 /**
- * All supported color format names. This can be used as an enum.
+ * All supported color format names.
  *
  * @category Internal
+ * @enum
  */
-export declare const ColorFormatName: { [FormatName in ColorFormatName]: FormatName; };
+export declare const ColorFormatName: { [Key in ColorFormatName]: Key; };
 /**
- * All supported color format names. This can be used as an enum.
+ * All supported color format names.
  *
  * @category Internal
+ * @enum
  */
 export type ColorFormatName = keyof typeof rawColorFormats;
 /**
@@ -210,9 +202,9 @@ export type ColorCoordsByFormat = {
  * @category Internal
  */
 export type ColorFormats = Readonly<{
-    [FormatName in ColorFormatName]: ColorFormatDefinition<'colorSpace' extends keyof (typeof rawColorFormats)[FormatName] ? Extract<(typeof rawColorFormats)[FormatName], {
+    [FormatName in ColorFormatName]: ColorFormatDefinition<Extract<(typeof rawColorFormats)[FormatName], {
         colorSpace: any;
-    }>['colorSpace'] : FormatName>;
+    }>['colorSpace'], FormatName>;
 }>;
 /**
  * All supported color formats.
@@ -221,17 +213,25 @@ export type ColorFormats = Readonly<{
  */
 export declare const colorFormats: ColorFormats;
 /**
- * All available color space names.
+ * All supported color space names.
  *
  * @category Internal
+ * @enum
  */
 export type ColorSpaceName = Values<typeof rawColorFormats>['colorSpace'];
+/**
+ * All supported color space names.
+ *
+ * @category Internal
+ * @enum
+ */
+export declare const ColorSpaceName: { [Key in ColorSpaceName]: Key; };
 /**
  * All value types for all supported color formats.
  *
  * @category Internal
  */
-export type ColorValues = {
+export type ColorValue = {
     [FormatName in ColorFormatName]: Record<keyof (typeof rawColorFormats)[FormatName]['coords'], number>;
 };
 /**
@@ -239,16 +239,22 @@ export type ColorValues = {
  *
  * @category Color Format
  */
-export declare const colorSpaces: Record<"rgb" | "lab" | "oklab", Record<"rgb" | "hsl" | "hwb" | "lab" | "lch" | "oklab" | "oklch", ColorFormatDefinition<string>>>;
+export declare const colorFormatsBySpace: { [ColorSpace in ColorSpaceName]: { [ColorFormat in ColorFormatName]: ColorFormatDefinition<ColorSpace, ColorFormat>; }; };
 /**
- * All color format names in an array.
+ * All possible coordinate names for all supported color formats in a union.
  *
  * @category Internal
  */
-export declare const colorFormatNames: ColorFormatName[];
+export type ColorCoordinateName = keyof UnionToIntersection<Values<typeof rawColorFormats>['coords']>;
 /**
- * All possible coordinate names for all supported color formats in a union.
+ * A single color format definition.
  *
  * @category Internal
  */
-export type ColorCoordinateName = keyof UnionToIntersection<Values<typeof rawColorFormats>['coords']>;
+export type ColorFormatDefinition<ColorSpace extends ColorSpaceName = any, ColorFormat extends ColorFormatName = any> = {
+    /** Which exact color coordinates exist in here depends on the set color space. */
+    coords: Record<ColorCoordsByFormat[ColorFormat], ColorCoordinateDefinition>;
+    /** This name for this color to be used in `Colorjs.to()`. Defaults to the color format key. */
+    colorSpace: ColorSpace;
+    colorFormat: ColorFormat;
+};

package/dist/{color-formats.js → color-class/color-formats.js}

@@ -1,4 +1,4 @@
-import { getObjectTypedEntries, getObjectTypedKeys, getOrSet, mapObjectValues, } from '@augment-vir/common';
+import { arrayToObject, getObjectTypedEntries, getObjectTypedValues, getOrSet, mapObjectValues, } from '@augment-vir/common';
 /**
  * All raw supported color formats.
  *
@@ -145,9 +145,10 @@ export const rawColorFormats = {
     },
 };
 /**
- * All supported color format names. This can be used as an enum.
+ * All supported color format names.
  *
  * @category Internal
+ * @enum
  */
 export const ColorFormatName = mapObjectValues(rawColorFormats, (colorName) => colorName);
 /**
@@ -155,21 +156,34 @@ export const ColorFormatName = mapObjectValues(rawColorFormats, (colorName) => c
  *
  * @category Color Format
  */
-export const colorFormats = rawColorFormats;
+export const colorFormats = mapObjectValues(rawColorFormats, (colorFormatName, colorFormatValue) => {
+    return {
+        ...colorFormatValue,
+        colorFormat: colorFormatName,
+    };
+});
+/**
+ * All supported color space names.
+ *
+ * @category Internal
+ * @enum
+ */
+export const ColorSpaceName = arrayToObject(getObjectTypedValues(rawColorFormats), (format) => {
+    return {
+        key: format.colorSpace,
+        value: format.colorSpace,
+    };
+}, {
+    useRequired: true,
+});
 /**
  * All color formats grouped by their color space.
  *
  * @category Color Format
  */
-export const colorSpaces = getObjectTypedEntries(colorFormats).reduce((accum, [colorFormatName, colorFormatDefinition,]) => {
+export const colorFormatsBySpace = getObjectTypedEntries(colorFormats).reduce((accum, [colorFormatName, colorFormatDefinition,]) => {
     getOrSet(accum, colorFormatDefinition.colorSpace, () => {
         return {};
     })[colorFormatName] = colorFormatDefinition;
     return accum;
 }, {});
-/**
- * All color format names in an array.
- *
- * @category Internal
- */
-export const colorFormatNames = getObjectTypedKeys(colorFormats);

package/dist/{color.d.ts → color-class/color.d.ts}

@@ -1,6 +1,6 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type RequireExactlyOne } from 'type-fest';
-import { type ColorCoordsByFormat, type ColorFormatName, type ColorValues, type HexColor } from './color-formats.js';
+import { ColorFormatName, type ColorCoordsByFormat, type ColorValue, type HexColor } from './color-formats.js';
 /**
  * An update to an existing {@link Color} instance. Used in {@link Color.set}.
  *
@@ -14,11 +14,11 @@ export type ColorUpdate = RequireExactlyOne<{
 }>;
 /**
  * The values of all supported color formats for a given {@link Color} instance. Accessed via
- * {@link Color.allColors}.
+ * `Color.allColors`.
  *
  * @category Internal
  */
-export type AllColorsValues = ColorValues & {
+export type AllColorsValues = ColorValue & {
     hex: HexColor;
     names: string[];
 };
@@ -35,6 +35,9 @@ export type AllColorsValues = ColorValues & {
  */
 export declare class Color {
     #private;
+    constructor(
+    /** Any valid CSS color string or an object of color coordinate values. */
+    initValue: string | Readonly<ColorUpdate>);
     /**
      * Create a new {@link Color} instance by parsing the output of another instance's
      * {@link Color.serialize} method.
@@ -80,9 +83,6 @@ export declare class Color {
             h: number;
         };
     };
-    constructor(
-    /** Any valid CSS color string or an object of color coordinate values. */
-    initValue: string | Readonly<ColorUpdate>);
     /** Create a new {@link Color} instance that matches this one exactly. */
     clone(): Color;
     /**

package/dist/{color.js → color-class/color.js}

@@ -1,8 +1,8 @@
 import { assert, assertWrap, check } from '@augment-vir/assert';
-import { copyThroughJson, filterMap, getObjectTypedEntries, joinWithFinalConjunction, mapObjectValues, round, } from '@augment-vir/common';
+import { copyThroughJson, filterMap, getEnumValues, getObjectTypedEntries, getObjectTypedKeys, joinWithFinalConjunction, mapObjectValues, round, } from '@augment-vir/common';
 import colorNames from 'color-name';
 import { clampGamut, converter, formatHex, parse } from 'culori';
-import { colorFormatNames, colorFormats, } from './color-formats.js';
+import { ColorFormatName, colorFormats, } from './color-formats.js';
 import { maxColorNameLength } from './color-name-length.js';
 /**
  * A `Color` class with state and the following features:
@@ -16,6 +16,11 @@ import { maxColorNameLength } from './color-name-length.js';
  * @category Color
  */
 export class Color {
+    constructor(
+    /** Any valid CSS color string or an object of color coordinate values. */
+    initValue) {
+        this.set(initValue);
+    }
     /**
      * Create a new {@link Color} instance by parsing the output of another instance's
      * {@link Color.serialize} method.
@@ -69,11 +74,6 @@ export class Color {
             h: 0,
         },
     };
-    constructor(
-    /** Any valid CSS color string or an object of color coordinate values. */
-    initValue) {
-        this.set(initValue);
-    }
     /** Create a new {@link Color} instance that matches this one exactly. */
     clone() {
         return Color.deserialize(this.serialize());
@@ -109,7 +109,7 @@ export class Color {
             const colorFormatDefinition = colorFormats[colorFormatName];
             const orderedColorCoords = Object.values(mapObjectValues(colorFormatDefinition.coords, (coordName) => {
                 const coordValue = colorValues[coordName];
-                const coordDefinition = assertWrap.isDefined(colorFormatDefinition.coords[coordName]);
+                const coordDefinition = colorFormatDefinition.coords[assertWrap.isKeyOf(coordName, colorFormatDefinition.coords)];
                 const rawCoordValue = coordValue != undefined &&
                     coordValue >= coordDefinition.min &&
                     coordValue <= coordDefinition.max
@@ -125,7 +125,7 @@ export class Color {
      * internal color object.
      */
     pullFromInternalColor() {
-        colorFormatNames.forEach((colorFormatName) => {
+        getEnumValues(ColorFormatName).forEach((colorFormatName) => {
             const colorFormatDefinition = colorFormats[colorFormatName];
             const originalColorDefinition = check.isKeyOf(this.#internalColor.mode, colorFormats)
                 ? colorFormats[this.#internalColor.mode]
@@ -137,11 +137,12 @@ export class Color {
             if (!converted) {
                 assert.never(`Failed to convert color '${JSON.stringify(this.#internalColor)}' to '${colorFormatName}'.`);
             }
-            Object.keys(this[colorFormatName]).forEach((coordName) => {
+            getObjectTypedKeys(this[colorFormatName]).forEach((coordName) => {
                 const coordValue = converted[coordName];
+                const coordinateDefinition = colorFormatDefinition.coords[assertWrap.isKeyOf(coordName, colorFormatDefinition.coords)];
                 if (coordValue != undefined) {
-                    this._allColors[colorFormatName][coordName] = round((coordValue || 0) * (colorFormatDefinition.coords[coordName]?.factor || 1), {
-                        digits: colorFormatDefinition.coords[coordName]?.digits || 0,
+                    this._allColors[colorFormatName][coordName] = round((coordValue || 0) * (coordinateDefinition.factor || 1), {
+                        digits: coordinateDefinition.digits || 0,
                     });
                 }
             });

package/dist/contrast/contrast.d.ts

@@ -0,0 +1,229 @@
+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 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<FontWeight, number>;
+/**
+ * Contrast calculations produced by {@link calculateContrast}.
+ *
+ * @category Internal
+ */
+export type CalculatedContrast = {
+    /** The raw APCA LC contrast value. */
+    contrast: number;
+    /** The minimum font size for each font weight for the current `contrast` value. */
+    fontSizes: FontSizes;
+    /** The contrast level for the current `contrast` value. */
+    contrastLevel: ContrastLevel;
+};
+/**
+ * The value of each color may be any valid CSS color string.
+ *
+ * @category Internal
+ */
+export type CalculateContrastParams = {
+    foreground: string;
+    background: string;
+};
+/**
+ * Calculate contrast for the given color combination.
+ *
+ * @category Internal
+ */
+export declare function calculateContrast({ background, foreground, }: Readonly<CalculateContrastParams>): 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.
+ *
+ * @category Internal
+ */
+export declare function calculateFontSizes(contrast: number): FontSizes;
+/**
+ * Finds the color contrast level for the given contrast.
+ *
+ * @category Internal
+ */
+export declare function determineContrastLevel(contrast: number): ContrastLevel;
+/**
+ * Names for each {@link ContrastLevel}.
+ *
+ * @category Internal
+ */
+export declare enum ContrastLevelName {
+    SmallBodyText = "small-body",
+    BodyText = "body",
+    NonBodyText = "non-body",
+    Header = "header",
+    Placeholder = "placeholder",
+    Decoration = "decoration",
+    Invisible = "invisible"
+}
+/**
+ * User-facing labels for {@link ContrastLevelName}.
+ *
+ * @category Internal
+ */
+export declare const contrastLevelLabel: Record<ContrastLevelName, string>;
+/**
+ * All {@link ContrastLevelName} values in order from highest contrast to lowest.
+ *
+ * @category Internal
+ */
+export declare const orderedContrastLevelNames: readonly [ContrastLevelName.SmallBodyText, ContrastLevelName.BodyText, ContrastLevelName.NonBodyText, ContrastLevelName.Header, ContrastLevelName.Placeholder, ContrastLevelName.Decoration, ContrastLevelName.Invisible];
+/**
+ * Color contrast level details.
+ *
+ * @category Internal
+ */
+export type ContrastLevel = {
+    /** The minimum contrast level threshold for this contrast level. */
+    min: number;
+    /** The name corresponding to the smallest text or non-text item that this can be used for. */
+    name: ContrastLevelName;
+    /** Short description for this contrast level. */
+    description: string;
+    /** Name from the APCA guidelines (confusing). */
+    apcaName: string;
+    /** Description from the APCA guidelines (verbose). */
+    apcaDescription: string;
+};
+/**
+ * All color contrast levels corresponding to APCA bronze guidelines.
+ *
+ * @category Internal
+ */
+export declare const contrastLevels: readonly [{
+    readonly min: 90;
+    readonly name: ContrastLevelName.SmallBodyText;
+    readonly description: "Perfect for all sizes of text, even small body text.";
+    readonly apcaName: "small body text only";
+    readonly 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.";
+}, {
+    readonly min: 75;
+    readonly name: ContrastLevelName.BodyText;
+    readonly description: "Good for regular body text and anything larger.";
+    readonly apcaName: "body text okay";
+    readonly 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.";
+}, {
+    readonly min: 60;
+    readonly name: ContrastLevelName.NonBodyText;
+    readonly description: "Good for legible non-body text and anything larger.";
+    readonly apcaName: "fluent text only";
+    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.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.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.";
+}, {
+    readonly min: 15;
+    readonly name: ContrastLevelName.Decoration;
+    readonly description: "Only okay for decorations like graphics, borders, dividers, etc. Do not use for any text.";
+    readonly apcaName: "no text usage";
+    readonly 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.";
+}, {
+    readonly min: 0;
+    readonly name: ContrastLevelName.Invisible;
+    readonly description: "Effectively invisible for users.";
+    readonly apcaName: "invisible";
+    readonly apcaDescription: "This should be treated as invisible.";
+}];
+/**
+ * Type for {@link contrastLevelMinMap}.
+ *
+ * @category Internal
+ */
+export type ContrastLevelMinMap = {
+    [Min in ArrayElement<typeof contrastLevels>['min']]: Extract<ArrayElement<typeof contrastLevels>, {
+        min: Min;
+    }>;
+};
+/**
+ * A mapping of all color contrast levels mins to their contrast levels. Generated from
+ * {@link contrastLevels}.
+ *
+ * @category Internal
+ */
+export declare const contrastLevelMinMap: ContrastLevelMinMap;
+/**
+ * Type for {@link contrastLevelMinMap}.
+ *
+ * @category Internal
+ */
+export type ContrastLevelNameMap = {
+    [Name in ArrayElement<typeof contrastLevels>['name']]: Extract<ArrayElement<typeof contrastLevels>, {
+        name: Name;
+    }>;
+};
+/**
+ * A mapping of all color contrast levels mins to their contrast levels. Generated from
+ * {@link contrastLevels}.
+ *
+ * @category Internal
+ */
+export declare const contrastLevelNameMap: ContrastLevelNameMap;