@instructure/ui-color-utils 10.5.1-snapshot-3 → 10.5.1-snapshot-5

package/CHANGELOG.md

@@ -3,9 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [10.5.1-snapshot-3](https://github.com/instructure/instructure-ui/compare/v10.5.0...v10.5.1-snapshot-3) (2024-11-13)
+## [10.5.1-snapshot-5](https://github.com/instructure/instructure-ui/compare/v10.5.0...v10.5.1-snapshot-5) (2024-11-14)
 
-**Note:** Version bump only for package @instructure/ui-color-utils
+
+### Features
+
+* **ui-color-picker,ui-color-utils:** add callback for contrast validation information and export validation methods ([e756c7d](https://github.com/instructure/instructure-ui/commit/e756c7dde20158e82483a4541e916ee98a7a93ec))
 
 
 

package/es/contrastWithAlpha.js

@@ -0,0 +1,53 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { colorToRGB, colorToHex8 } from './conversions';
+import { overlayColors } from './overlayColors';
+import { contrast } from './contrast';
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Calculates two, not necesseraly opaque color's contrast on top of each other.
+ * The method assumes that the bottom color is on top of a white background (only important if it isn't opaque)
+ * @module contrastWithAlpha
+ * @param {String} color1
+ * @param {String} color2
+ * @param {Number} decimalPlaces
+ * @returns {Number} color contrast ratio
+ */
+const contrastWithAlpha = (color1, color2) => {
+  const c1RGBA = colorToRGB(color1);
+  const c2RGBA = colorToRGB(color2);
+  const c1OnWhite = overlayColors({
+    r: 255,
+    g: 255,
+    b: 255,
+    a: 1
+  }, c1RGBA);
+  const c2OnC1OnWhite = overlayColors(c1OnWhite, c2RGBA);
+  return contrast(colorToHex8(c1OnWhite), colorToHex8(c2OnC1OnWhite), 2);
+};
+export { contrastWithAlpha };

package/es/index.js

@@ -27,6 +27,9 @@ export { darken } from './darken';
 export { lighten } from './lighten';
 export { contrast } from './contrast';
 export { isValid } from './isValid';
+export { overlayColors } from './overlayColors';
+export { contrastWithAlpha } from './contrastWithAlpha';
+export { validateContrast } from './validateContrast';
 export { color2hex, colorToHex8, colorToHsva, colorToHsla, colorToRGB } from './conversions';
 import { color2hex, colorToHex8, colorToHsva, colorToHsla, colorToRGB } from './conversions';
 

package/es/overlayColors.js

@@ -0,0 +1,55 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * @typedef {Object} RGBAResult
+ * @property {Number} r - Red component as a string
+ * @property {Number} g - Green component as a string
+ * @property {Number} b - Blue component as a string
+ * @property {Number} a - Alpha component as a string
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Place two RGBA colors on top of each other. The second one (c2) goes on top.
+ * The method calculates what color would be visible. If the second color (c2) is opaque, the result
+ * will be c2, if fully transparent, c1. If anything in between, it calculates the real color.
+ * Alpha is always set to 1 after the calculation
+ * @module overlayColors
+ * @param {RGBAType} c1
+ * @param {RGBAType} c2
+ * @returns {RGBAType} color as rgb string
+ */
+const overlayColors = (c1, c2) => {
+  const alpha = 1 - (1 - c1.a) * (1 - c2.a);
+  return {
+    r: c2.r * c2.a / alpha + c1.r * c1.a * (1 - c2.a) / alpha,
+    g: c2.g * c2.a / alpha + c1.g * c1.a * (1 - c2.a) / alpha,
+    b: c2.b * c2.a / alpha + c1.b * c1.a * (1 - c2.a) / alpha,
+    a: 1
+  };
+};
+export { overlayColors };

package/es/validateContrast.js

@@ -0,0 +1,67 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * @typedef {Object} ValidatedContrasts
+ * @property {Boolean} isValidNormalText - Is the contrast high enough for normal text size?
+ * @property {Boolean} isValidLargeText - Is the contrast high enough for large text size?
+ * @property {Boolean} isValidGraphicsText - Is the contrast high enough for graphics text?
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Decides if the given contrast is sufficient for different text sizes and situations.
+ *
+ * According to WCAG 2.2
+ *
+ * AA level (https://www.w3.org/TR/WCAG22/#contrast-minimum)
+ *
+ * text: 4.5:1
+ *
+ * large text: 3:1
+ *
+ * non-text: 3:1 (https://www.w3.org/TR/WCAG22/#non-text-contrast)
+ *
+ *
+ * AAA level (https://www.w3.org/TR/WCAG22/#contrast-enhanced)
+ *
+ * text: 7:1
+ *
+ * large text: 4.5:1
+ *
+ * non-text: 3:1 (https://www.w3.org/TR/WCAG22/#non-text-contrast)
+ * @module validateContrast
+ * @param {Number} contrast
+ * @returns {ValidatedContrasts} validation object
+ */
+const validateContrast = (contrast, validationLevel) => {
+  return {
+    isValidNormalText: contrast >= (validationLevel === 'AAA' ? 7 : 4.5),
+    isValidLargeText: contrast >= (validationLevel === 'AAA' ? 4.5 : 3),
+    isValidGraphicsText: contrast >= 3
+  };
+};
+export { validateContrast };

package/lib/contrastWithAlpha.js

@@ -0,0 +1,58 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.contrastWithAlpha = void 0;
+var _conversions = require("./conversions");
+var _overlayColors = require("./overlayColors");
+var _contrast = require("./contrast");
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Calculates two, not necesseraly opaque color's contrast on top of each other.
+ * The method assumes that the bottom color is on top of a white background (only important if it isn't opaque)
+ * @module contrastWithAlpha
+ * @param {String} color1
+ * @param {String} color2
+ * @param {Number} decimalPlaces
+ * @returns {Number} color contrast ratio
+ */
+const contrastWithAlpha = (color1, color2) => {
+  const c1RGBA = (0, _conversions.colorToRGB)(color1);
+  const c2RGBA = (0, _conversions.colorToRGB)(color2);
+  const c1OnWhite = (0, _overlayColors.overlayColors)({
+    r: 255,
+    g: 255,
+    b: 255,
+    a: 1
+  }, c1RGBA);
+  const c2OnC1OnWhite = (0, _overlayColors.overlayColors)(c1OnWhite, c2RGBA);
+  return (0, _contrast.contrast)((0, _conversions.colorToHex8)(c1OnWhite), (0, _conversions.colorToHex8)(c2OnC1OnWhite), 2);
+};
+exports.contrastWithAlpha = contrastWithAlpha;

package/lib/index.js

@@ -45,6 +45,12 @@ Object.defineProperty(exports, "contrast", {
     return _contrast.contrast;
   }
 });
+Object.defineProperty(exports, "contrastWithAlpha", {
+  enumerable: true,
+  get: function () {
+    return _contrastWithAlpha.contrastWithAlpha;
+  }
+});
 Object.defineProperty(exports, "darken", {
   enumerable: true,
   get: function () {
@@ -64,11 +70,26 @@ Object.defineProperty(exports, "lighten", {
     return _lighten.lighten;
   }
 });
+Object.defineProperty(exports, "overlayColors", {
+  enumerable: true,
+  get: function () {
+    return _overlayColors.overlayColors;
+  }
+});
+Object.defineProperty(exports, "validateContrast", {
+  enumerable: true,
+  get: function () {
+    return _validateContrast.validateContrast;
+  }
+});
 var _alpha = require("./alpha");
 var _darken = require("./darken");
 var _lighten = require("./lighten");
 var _contrast = require("./contrast");
 var _isValid = require("./isValid");
+var _overlayColors = require("./overlayColors");
+var _contrastWithAlpha = require("./contrastWithAlpha");
+var _validateContrast = require("./validateContrast");
 var _conversions = require("./conversions");
 /*
  * The MIT License (MIT)

package/lib/overlayColors.js

@@ -0,0 +1,61 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.overlayColors = void 0;
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * @typedef {Object} RGBAResult
+ * @property {Number} r - Red component as a string
+ * @property {Number} g - Green component as a string
+ * @property {Number} b - Blue component as a string
+ * @property {Number} a - Alpha component as a string
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Place two RGBA colors on top of each other. The second one (c2) goes on top.
+ * The method calculates what color would be visible. If the second color (c2) is opaque, the result
+ * will be c2, if fully transparent, c1. If anything in between, it calculates the real color.
+ * Alpha is always set to 1 after the calculation
+ * @module overlayColors
+ * @param {RGBAType} c1
+ * @param {RGBAType} c2
+ * @returns {RGBAType} color as rgb string
+ */
+const overlayColors = (c1, c2) => {
+  const alpha = 1 - (1 - c1.a) * (1 - c2.a);
+  return {
+    r: c2.r * c2.a / alpha + c1.r * c1.a * (1 - c2.a) / alpha,
+    g: c2.g * c2.a / alpha + c1.g * c1.a * (1 - c2.a) / alpha,
+    b: c2.b * c2.a / alpha + c1.b * c1.a * (1 - c2.a) / alpha,
+    a: 1
+  };
+};
+exports.overlayColors = overlayColors;

package/lib/validateContrast.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateContrast = void 0;
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * @typedef {Object} ValidatedContrasts
+ * @property {Boolean} isValidNormalText - Is the contrast high enough for normal text size?
+ * @property {Boolean} isValidLargeText - Is the contrast high enough for large text size?
+ * @property {Boolean} isValidGraphicsText - Is the contrast high enough for graphics text?
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Decides if the given contrast is sufficient for different text sizes and situations.
+ *
+ * According to WCAG 2.2
+ *
+ * AA level (https://www.w3.org/TR/WCAG22/#contrast-minimum)
+ *
+ * text: 4.5:1
+ *
+ * large text: 3:1
+ *
+ * non-text: 3:1 (https://www.w3.org/TR/WCAG22/#non-text-contrast)
+ *
+ *
+ * AAA level (https://www.w3.org/TR/WCAG22/#contrast-enhanced)
+ *
+ * text: 7:1
+ *
+ * large text: 4.5:1
+ *
+ * non-text: 3:1 (https://www.w3.org/TR/WCAG22/#non-text-contrast)
+ * @module validateContrast
+ * @param {Number} contrast
+ * @returns {ValidatedContrasts} validation object
+ */
+const validateContrast = (contrast, validationLevel) => {
+  return {
+    isValidNormalText: contrast >= (validationLevel === 'AAA' ? 7 : 4.5),
+    isValidLargeText: contrast >= (validationLevel === 'AAA' ? 4.5 : 3),
+    isValidGraphicsText: contrast >= 3
+  };
+};
+exports.validateContrast = validateContrast;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-color-utils",
-  "version": "10.5.1-snapshot-3",
+  "version": "10.5.1-snapshot-5",
   "description": "A color utility library made by Instructure Inc.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -22,8 +22,8 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@instructure/ui-babel-preset": "10.5.1-snapshot-3",
-    "@instructure/ui-test-utils": "10.5.1-snapshot-3",
+    "@instructure/ui-babel-preset": "10.5.1-snapshot-5",
+    "@instructure/ui-test-utils": "10.5.1-snapshot-5",
     "@types/tinycolor2": "^1.4.6"
   },
   "dependencies": {

package/src/contrastWithAlpha.ts

@@ -0,0 +1,50 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { colorToRGB, colorToHex8 } from './conversions'
+import { overlayColors } from './overlayColors'
+import { contrast } from './contrast'
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Calculates two, not necesseraly opaque color's contrast on top of each other.
+ * The method assumes that the bottom color is on top of a white background (only important if it isn't opaque)
+ * @module contrastWithAlpha
+ * @param {String} color1
+ * @param {String} color2
+ * @param {Number} decimalPlaces
+ * @returns {Number} color contrast ratio
+ */
+const contrastWithAlpha = (color1: string, color2: string): number => {
+  const c1RGBA = colorToRGB(color1)
+  const c2RGBA = colorToRGB(color2)
+  const c1OnWhite = overlayColors({ r: 255, g: 255, b: 255, a: 1 }, c1RGBA)
+  const c2OnC1OnWhite = overlayColors(c1OnWhite, c2RGBA)
+
+  return contrast(colorToHex8(c1OnWhite), colorToHex8(c2OnC1OnWhite), 2)
+}
+
+export { contrastWithAlpha }

package/src/index.ts

@@ -27,6 +27,9 @@ export { darken } from './darken'
 export { lighten } from './lighten'
 export { contrast } from './contrast'
 export { isValid } from './isValid'
+export { overlayColors } from './overlayColors'
+export { contrastWithAlpha } from './contrastWithAlpha'
+export { validateContrast } from './validateContrast'
 export {
   color2hex,
   colorToHex8,

package/src/overlayColors.ts

@@ -0,0 +1,58 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { RGBAType } from './colorTypes'
+
+/**
+ * @typedef {Object} RGBAResult
+ * @property {Number} r - Red component as a string
+ * @property {Number} g - Green component as a string
+ * @property {Number} b - Blue component as a string
+ * @property {Number} a - Alpha component as a string
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Place two RGBA colors on top of each other. The second one (c2) goes on top.
+ * The method calculates what color would be visible. If the second color (c2) is opaque, the result
+ * will be c2, if fully transparent, c1. If anything in between, it calculates the real color.
+ * Alpha is always set to 1 after the calculation
+ * @module overlayColors
+ * @param {RGBAType} c1
+ * @param {RGBAType} c2
+ * @returns {RGBAType} color as rgb string
+ */
+const overlayColors = (c1: RGBAType, c2: RGBAType): RGBAType => {
+  const alpha = 1 - (1 - c1.a) * (1 - c2.a)
+  return {
+    r: (c2.r * c2.a) / alpha + (c1.r * c1.a * (1 - c2.a)) / alpha,
+    g: (c2.g * c2.a) / alpha + (c1.g * c1.a * (1 - c2.a)) / alpha,
+    b: (c2.b * c2.a) / alpha + (c1.b * c1.a * (1 - c2.a)) / alpha,
+    a: 1
+  }
+}
+
+export { overlayColors }

package/src/validateContrast.ts

@@ -0,0 +1,77 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+interface ValidatedContrasts {
+  isValidNormalText: boolean
+  isValidLargeText: boolean
+  isValidGraphicsText: boolean
+}
+
+/**
+ * @typedef {Object} ValidatedContrasts
+ * @property {Boolean} isValidNormalText - Is the contrast high enough for normal text size?
+ * @property {Boolean} isValidLargeText - Is the contrast high enough for large text size?
+ * @property {Boolean} isValidGraphicsText - Is the contrast high enough for graphics text?
+ */
+
+/**
+ * ---
+ * category: utilities
+ * ---
+ * Decides if the given contrast is sufficient for different text sizes and situations.
+ *
+ * According to WCAG 2.2
+ *
+ * AA level (https://www.w3.org/TR/WCAG22/#contrast-minimum)
+ *
+ * text: 4.5:1
+ *
+ * large text: 3:1
+ *
+ * non-text: 3:1 (https://www.w3.org/TR/WCAG22/#non-text-contrast)
+ *
+ *
+ * AAA level (https://www.w3.org/TR/WCAG22/#contrast-enhanced)
+ *
+ * text: 7:1
+ *
+ * large text: 4.5:1
+ *
+ * non-text: 3:1 (https://www.w3.org/TR/WCAG22/#non-text-contrast)
+ * @module validateContrast
+ * @param {Number} contrast
+ * @returns {ValidatedContrasts} validation object
+ */
+const validateContrast = (
+  contrast: number,
+  validationLevel?: 'AA' | 'AAA'
+): ValidatedContrasts => {
+  return {
+    isValidNormalText: contrast >= (validationLevel === 'AAA' ? 7 : 4.5),
+    isValidLargeText: contrast >= (validationLevel === 'AAA' ? 4.5 : 3),
+    isValidGraphicsText: contrast >= 3
+  }
+}
+
+export { validateContrast }