@adeira/css-colors - npm Package Compare versions

Comparing version 2.0.0 to 2.1.0

css-colors/CHANGELOG.md

 # Unreleased
 
+# 2.1.0
+
+Note for all Flow users: all projects in [`adeira/universe`](https://github.com/adeira/universe) now use implicit exact Flow types (`{}` for strict objects and `{ ... }` for open objects, syntax `{||}` is deprecated). We do not expect any issues as long as you are using `exact_by_default=true` Flow option.
+
+Other changes:
+
+- New functions `calculateContrastRatio` and `isAccessible` were added.
+- Functions `isDark` and `isBright` has been deprecated. You can use `isAccessible` function to make a better decision about colors contrast (for text and background colors for example). The following code snippets show possible migration strategy:
+
+  ```js
+  isDark(rgb);
+
+  // replace with:
+  isAccessible(rgb, [255, 255, 255]); // or better to use you actual bg/fg color
+  ```
+
+  ```js
+  isBright(rgb);
+
+  // replace with:
+  isAccessible(rgb, [0, 0, 0]); // or better to use you actual bg/fg color
+  ```
+
 # 2.0.0
@@ -10,1 +33,5 @@
 - added new functions `isBright` and `isDark`
+
+# 1.0.0
+
+Initial stable release.

css-colors/package.json

 {
-  "main": "src/index",
-  "module": "src/index.mjs",
   "name": "@adeira/css-colors",
   "description": "Utility functions for working with CSS/HTML colors.",
   "homepage": "https://github.com/adeira/universe/tree/master/src/css-colors",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "sideEffects": false,
   "private": false,
+  "main": "./src/index.js",
+  "type": "commonjs",
   "license": "MIT",
   "dependencies": {
-    "@adeira/js": "^1.3.0",
-    "@babel/runtime": "^7.12.5"
+    "@adeira/js": "^2.1.0",
+    "@babel/runtime": "^7.14.6"
   }
-}
+}

css-colors/README.md

@@ -19,3 +19,3 @@ Utility functions for working with CSS/HTML colors.
 
-The imported `cssColorNames` is actually a `Map` of all CSS keywords.
+The imported `cssColorNames` is a [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) of all CSS keywords, so you can use any available `Map` methods.
 
@@ -30,19 +30,37 @@ ## Is it a color?
 isColor('rgb(255, 255, 128)'); // true
-isColor('hsl(50, 33%, 25)'); // false (should be 25%)
+isColor('transparent'); // true
+isColor('currentcolor'); // true
+isColor('hsl(50, 33%, 25)'); // false (last number should be 25%)
 ```
 
-## Is the color bright or dark?
+## What is the color contrast ratio?
 
-This function can be used to detect whether the color is bright or dark so you can decide whether you should use white or black text for the color background (for example).
+This function takes triplet of colors for foreground and background colors and calculates their contrast ratio (from 1:1 for no contrast up to 25:1 for excellent contrast):
 
 ```js
-import { isDark, isBright } from '@adeira/css-colors';
+import { calculateContrastRatio } from '@adeira/css-colors';
 
-isDark([0, 0, 0]); // true (it's black)
-isBright([0, 0, 0]); // false
+calculateContrastRatio([130, 242, 75], [119, 46, 242]); // 4.27 (4.27:1)
+```
 
-isDark([255, 255, 255]); // false (it's white)
-isBright([255, 255, 255]); // true
+See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast
+
+## Is the pair of colors accessible?
+
+Allows you to decide whether a pair of two colors (typically foreground and background) is accessible:
+
+```js
+import { isAccessible } from '@adeira/css-colors';
+
+isAccessible([0, 0, 0], [255, 255, 255]); // true (black and white combo)
+
+// optionally, you can specify context of these colors and success criteria for accessibility:
+isAccessible([64, 32, 17], [201, 120, 136], 'NORMAL_TEXT', 'AAA'); // false
+isAccessible([64, 32, 17], [201, 120, 136], 'NORMAL_TEXT', 'AA'); // true
+isAccessible([64, 32, 17], [201, 120, 136], 'LARGE_TEXT', 'AAA'); // true
+isAccessible([64, 32, 17], [201, 120, 136], 'GRAPHICAL_OBJECTS'); // true
 ```
 
+Note on colors accessibility: it can happen that some backgrounds are never accessible under **AAA** criteria. For example [`#FF1A1A`](https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FF1A1A) always fails "normal text" test for **AAA** criteria (no matter whether you choose completely white or completely black font).
+
 ## Normalize colors
@@ -66,1 +84,20 @@
 ```
+
+## Is the color bright or dark? (DEPRECATED)
+
+This function can be used to detect whether the color is bright or dark, so you can decide whether you should use white or black text for the color background (or vice versa):
+
+```js
+import { isDark, isBright } from '@adeira/css-colors';
+
+isDark([0, 0, 0]); // true (it's black)
+isBright([0, 0, 0]); // false
+
+isDark([144, 238, 144]); // false (lightgreen)
+isBright([144, 238, 144]); // true
+
+isDark([255, 255, 255]); // false (it's white)
+isBright([255, 255, 255]); // true
+```
+
+_Please note that while this function is simple, it takes into account only one color. Consider using [`calculateContrastRatio`](#what-is-the-color-contrast-ratio) and/or [`isAccessible`](#is-the-pair-of-colors-accessible) described above where you can specify 2 colors (for example, text and its background)._

css-colors/src/index.js

@@ -8,2 +8,8 @@ "use strict";
 });
+Object.defineProperty(exports, "calculateContrastRatio", {
+  enumerable: true,
+  get: function get() {
+    return _calculateContrastRatio.default;
+  }
+});
 Object.defineProperty(exports, "cssColorNames", {
@@ -27,2 +33,8 @@ enumerable: true,
 });
+Object.defineProperty(exports, "isAccessible", {
+  enumerable: true,
+  get: function get() {
+    return _isAccessible.default;
+  }
+});
 Object.defineProperty(exports, "isBright", {
@@ -53,2 +65,4 @@ enumerable: true,
 
+var _calculateContrastRatio = _interopRequireDefault(require("./calculateContrastRatio"));
+
 var _cssColorNames = _interopRequireDefault(require("./cssColorNames"));
@@ -60,2 +74,4 @@
 
+var _isAccessible = _interopRequireDefault(require("./isAccessible"));
+
 var _isBright = _interopRequireDefault(require("./isBright"));
@@ -62,0 +78,0 @@

css-colors/src/isBright.js

@@ -12,4 +12,16 @@ "use strict";
 
+/**
+ * @deprecated It's a bit funky to take into account only one color and decide whether it's bright
+ * or not. While one color might be bright, it doesn't say much about colors accessibility and it
+ * doesn't allow to compare text vs. background colors for example. These two calls are basically
+ * equivalent:
+ *
+ * ```js
+ * isBright(rgb);
+ *
+ * isAccessible(rgb, [0, 0, 0]); // comparing with black background
+ * ```
+ */
 function isBright(rgb) {
   return (0, _calculateBrightness.default)(rgb) >= 128;
 }

css-colors/src/isDark.js

@@ -12,4 +12,16 @@ "use strict";
 
+/**
+ * @deprecated It's a bit funky to take into account only one color and decide whether it's bright
+ * or not. While one color might be bright, it doesn't say much about colors accessibility and it
+ * doesn't allow to compare text vs. background colors for example. These two calls are basically
+ * equivalent:
+ *
+ * ```js
+ * isDark(rgb);
+ *
+ * isAccessible(rgb, [255, 255, 255]); // comparing with white background
+ * ```
+ */
 function isDark(rgb) {
   return (0, _calculateBrightness.default)(rgb) < 128;
 }

No alert changes

Improved metrics

Total package byte prevSize

34875

increased by13.99%

Lines of code

314

increased by14.18%

Number of lines in readme file

101

increased by57.81%

Worsened metrics

Number of package files

26

decreased by-16.13%

Dependency changes

• + Added@adeira/js@2.1.1(transitive)

• - Removed@adeira/js@1.3.0(transitive)

• Updated@adeira/js@^2.1.0

• Updated@babel/runtime@^7.14.6