font-color-contrast - npm Package Compare versions

Comparing version 9.1.0 to 10.0.0

package.json

 {
   "name": "font-color-contrast",
-  "version": "9.1.0",
+  "version": "10.0.0",
   "description": "JavaScript module to use black or white font according to the given background color",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

readme.md

 # font-color-contrast
 
-[![npm](https://img.shields.io/npm/v/font-color-contrast.svg?maxAge=2592000)](https://www.npmjs.com/package/font-color-contrast)
+[![npm](https://img.shields.io/npm/v/font-color-contrast.svg)](https://www.npmjs.com/package/font-color-contrast)
 [![CI Pipeline](https://github.com/russoedu/font-color-contrast/actions/workflows/main.yml/badge.svg)](https://github.com/russoedu/font-color-contrast/actions/workflows/main.yml)
@@ -11,4 +11,6 @@ [![Build Status](https://scrutinizer-ci.com/g/russoedu/font-color-contrast/badges/build.png?b=master)](https://scrutinizer-ci.com/g/russoedu/font-color-contrast/build-status/master)
 
-NodeJS module to select black or white to a font according to the background.
+JavaScript module to select black or white to a font according to the background for the best possible contrast.
 
+Calculates the best color (black or white) to contrast with the passed color using the algorithm from https://alienryderflex.com/hsp.html
+
 ## Installation
@@ -20,7 +22,21 @@
 
-You can use the module 3 ways:
-- with a hexadecimal color (number or string), i.e. fontColor("#f7d4fc") or fontColor(0xf7d56a) or even fontColor(16242026)
-- with an RGB separated by comma color (number), i.e. fontColor(223, 0, 255)
-- with an RGB array color (number), i.e. fontColor([223, 0, 255])
+You can use the module 4 ways, with an optional parameter (from 0 to 1) for contrast threshold:
+- with a hexadecimal color string
+  - fontColor('#f7d4fc')
+  - fontColor('f7d4fc')
+  - fontColor('f7d4fc', 0.2)
+- with a color number
+  - fontColor(0xf7d56a)
+  - fontColor(16242026)
+  - fontColor(16242026, 0.8)
+- with an array of numbers with the RGB color:
+  - fontColor([223, 0, 255])
+  - fontColor([0xf7, 0, 0xff])
+  - fontColor([0xf7, 0, 0xff], 0.4)
+- with the RGB color numbers:
+  - fontColor(223, 0, 255)
+  - fontColor(0xf7, 0, 0xff)
+  - fontColor(0xf7, 0, 0xff, 0.4)
 
+Example:
 ```Typescript
@@ -35,8 +51,6 @@ import fontColorContrast from 'font-color-contrast'
 
-const myRgbBg = {
-  red: 0,
-  green: 204,
-  blue: 153
-}
-const fontColor = fontColorContrast(myRgbBg.red, myRgbBg.green, myRgbBg.blue) // '#000000'
+const red = 0
+const green = 204
+const blue = 153
+const fontColor = fontColorContrast(red, green, blue) // '#000000'
 
@@ -48,2 +62,12 @@ const myArrayBg = [0, green: 204, blue: 153]
 
+Optionally, you can pass the contrast threshold (defaults to 0.5). This will affect the resulting font color. The use of this parameter is to control the [WCAG conformance levels](https://www.w3.org/WAI/WCAG2A-Conformance).
+
+ ```Typescript
+import fontColorContrast from 'font-color-contrast'
+
+fontColorContrast('#645466', 0) // '#000000'
+fontColorContrast('#645466', 1) // '#ffffff'
+
+```
+
 The 4 possible overflows are described next:
@@ -53,6 +77,8 @@
 /**
- * @param hex The hex color number that must be a valid hexadecimal color number, with 6 characters, to work correctly
+ * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
+ * @param hex The hex color number that must be a valid hexadecimal color number, with 6 characters, to work correctly.
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @example fontColorContrast(0XF3DC56) === fontColorContrast(15981654)
  */
-function fontColorContrast (hex: number): '#ffffff' | '#000000'
+function fontColorContrast (hex: number, threshold?: number): '#ffffff' | '#000000'
 ```
@@ -62,6 +88,8 @@
 /**
- * @param hex The hex color string that must be a valid hexadecima color number to work correctly. Works with or without '#', with 3 or 6 color chars
+ * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
+ * @param hex The hex color string that must be a valid hexadecima color number to work correctly. Works with or without '#', with 3 or 6 color chars.
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @example fontColorContrast('00FFDD') === fontColorContrast('0FD') === fontColorContrast('#00FFDD') === fontColorContrast('#0FD')
  */
- function fontColorContrast (hex: string): '#ffffff' | '#000000'
+ function fontColorContrast (hex: string, threshold?: number): '#ffffff' | '#000000'
 ```
@@ -71,8 +99,10 @@
 /**
- * @param red The red portion of the color. Must be a number between 0 and 255
- * @param green The green portion of the color. Must be a number between 0 and 255
- * @param blue The blue portion of the color. Must be a number between 0 and 255
- * @example fontColorContrast('00', 'F3', D8) === fontColorContrast(0, 243, 216) === fontColorContrast(0x0, 0xF3, 0xd8)
+ * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
+ * @param red The red portion of the color. Must be a number between 0 and 255.
+ * @param green The green portion of the color. Must be a number between 0 and 255.
+ * @param blue The blue portion of the color. Must be a number between 0 and 255.
+ * @example fontColorContrast('00', 'F3', D8) === fontColorContrast(0, 243, 216) === fontColorContrast(0x0, 0xF3, 0xd8).
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  */
-function fontColorContrast (red: number, green: number, blue: number): '#ffffff' | '#000000'
+function fontColorContrast (red: number, green: number, blue: number, threshold?: number): '#ffffff' | '#000000'
 ```
@@ -82,6 +112,8 @@
 /**
- * @param redGreenBlue Array with red, green and blue. Each value must be a number between 0 and 255
+ * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
+ * @param redGreenBlue Array with red, green and blue. Each value must be a number between 0 and 255.
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @example fontColorContrast(['00', 'F3', 'D8']) === fontColorContrast([0, 243, 216]) === fontColorContrast([0x0, 0xF3, 0xd8])
  */
-function fontColorContrast (redGreenBlue: number[]): '#ffffff' | '#000000'
+function fontColorContrast(redGreenBlue: number[], threshold?: number): '#ffffff' | '#000000'
 ```
@@ -95,2 +127,4 @@
 
+These examples are using the default 0.5 threshold.
+
 ### WebSafe colors
@@ -115,1 +149,4 @@ ![Sample with WebSafe colors](https://github.com/russoedu/font-color-contrast/blob/master/websafe-colors.jpeg?raw=true)
 Updated algorithm from https://alienryderflex.com/hsp.html with new thresholds for better contrast.
+
+### 10.0.0
+Included the optional threshold parameter (thanks, [franciscohanna92](https://github.com/franciscohanna92)).

src/index.test.ts

@@ -55,3 +55,3 @@ import fontColorContrast from './index'
     const c5 = fontColorContrast(0)
-    const c6 = fontColorContrast(0x00000)
+    const c6 = fontColorContrast(0x0)
 
@@ -99,6 +99,5 @@ expect(c1).toBe('#ffffff')
     const c4 = fontColorContrast(6575206) // 0X645466 converted to decimal
-    const c5 = fontColorContrast(0x64, 0x54, 0x66)
-    const c6 = fontColorContrast([64, 54, 66])
-    const c7 = fontColorContrast([0x64, 0x54, 0x66])
-    const c8 = fontColorContrast([64, 54, 66])
+    const c5 = fontColorContrast([100, 84, 102])
+    const c6 = fontColorContrast([0x64, 0x54, 0x66])
+    const c7 = fontColorContrast([100, 84, 102])
     expect(c1).toBe('#ffffff')
@@ -111,3 +110,2 @@ expect(c2).toBe('#ffffff')
     expect(c7).toBe('#ffffff')
-    expect(c8).toBe('#ffffff')
   })
@@ -126,2 +124,31 @@
   })
+
+  test('threshold param should alter result font color with a close to the limit color', () => {
+    // This color contrast is 0.4915548540582736
+    const hexString = '#837984'
+    expect(fontColorContrast(hexString)).toBe('#ffffff')
+    expect(fontColorContrast(hexString, 0.49)).toBe('#000000')
+    expect(fontColorContrast(hexString, 0)).toBe('#000000')
+    expect(fontColorContrast(hexString, 1)).toBe('#ffffff')
+
+    const hexNumber = 0x837984
+    expect(fontColorContrast(hexNumber)).toBe('#ffffff')
+    expect(fontColorContrast(hexNumber, 0)).toBe('#000000')
+    expect(fontColorContrast(hexNumber, 0.49)).toBe('#000000')
+    expect(fontColorContrast(hexNumber, 1)).toBe('#ffffff')
+
+    const rbgArray = [131, 121, 132]
+    expect(fontColorContrast(rbgArray)).toBe('#ffffff')
+    expect(fontColorContrast(rbgArray, 0)).toBe('#000000')
+    expect(fontColorContrast(rbgArray, 0.49)).toBe('#000000')
+    expect(fontColorContrast(rbgArray, 1)).toBe('#ffffff')
+
+    const red = 131
+    const green = 121
+    const blue = 132
+    expect(fontColorContrast(red, green, blue)).toBe('#ffffff')
+    expect(fontColorContrast(red, green, blue, 0)).toBe('#000000')
+    expect(fontColorContrast(red, green, blue, 0.49)).toBe('#000000')
+    expect(fontColorContrast(red, green, blue, 1)).toBe('#ffffff')
+  })
 })

src/index.ts

@@ -12,33 +12,38 @@ const hashRegEx = /#/
  * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
- * @param hex The hex color number that must be a valid hexadecimal color number, with 6 characters, to work correctly
+ * @param hex The hex color number that must be a valid hexadecimal color number, with 6 characters, to work correctly.
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @example fontColorContrast(0XF3DC56) === fontColorContrast(15981654)
  */
-function fontColorContrast (hex: number): '#ffffff' | '#000000'
+function fontColorContrast (hex: number, threshold?: number): '#ffffff' | '#000000'
 
 /**
  * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
- * @param hex The hex color string that must be a valid hexadecima color number to work correctly. Works with or without '#', with 3 or 6 color chars
+ * @param hex The hex color string that must be a valid hexadecima color number to work correctly. Works with or without '#', with 3 or 6 color chars.
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @example fontColorContrast('00FFDD') === fontColorContrast('0FD') === fontColorContrast('#00FFDD') === fontColorContrast('#0FD')
  */
- function fontColorContrast (hex: string): '#ffffff' | '#000000'
+ function fontColorContrast (hex: string, threshold?: number): '#ffffff' | '#000000'
 
 /**
  * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
- * @param red The red portion of the color. Must be a number between 0 and 255
- * @param green The green portion of the color. Must be a number between 0 and 255
- * @param blue The blue portion of the color. Must be a number between 0 and 255
- * @example fontColorContrast('00', 'F3', D8) === fontColorContrast(0, 243, 216) === fontColorContrast(0x0, 0xF3, 0xd8)
+ * @param red The red portion of the color. Must be a number between 0 and 255.
+ * @param green The green portion of the color. Must be a number between 0 and 255.
+ * @param blue The blue portion of the color. Must be a number between 0 and 255.
+ * @example fontColorContrast('00', 'F3', D8) === fontColorContrast(0, 243, 216) === fontColorContrast(0x0, 0xF3, 0xd8).
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  */
-function fontColorContrast (red: number, green: number, blue: number): '#ffffff' | '#000000'
+function fontColorContrast (red: number, green: number, blue: number, threshold?: number): '#ffffff' | '#000000'
 
 /**
  * Analyses the color (normally used in the background) and retrieves what color (black or white) has a better contrast.
- * @param redGreenBlue Array with red, green and blue. Each value must be a number between 0 and 255
+ * @param redGreenBlue Array with red, green and blue. Each value must be a number between 0 and 255.
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @example fontColorContrast(['00', 'F3', 'D8']) === fontColorContrast([0, 243, 216]) === fontColorContrast([0x0, 0xF3, 0xd8])
  */
-function fontColorContrast (redGreenBlue: number[]): '#ffffff' | '#000000'
+function fontColorContrast(redGreenBlue: number[], threshold?: number): '#ffffff' | '#000000'
 
-function fontColorContrast (hexColorOrRedOrArray: string | number | number[], green?: number, blue?: number) {
+function fontColorContrast (hexColorOrRedOrArray: string | number | number[], greenOrThreshold?: number, blue?: number, threshold?: number) {
   let red = 0
-  isRGB = !!(green !== undefined && blue !== undefined)
+  let green = 0
+  isRGB = !!(blue !== undefined)
   isArray = Array.isArray(hexColorOrRedOrArray)
@@ -50,4 +55,5 @@ isHexString = typeof hexColorOrRedOrArray === 'string' && !isRGB
     [red, green, blue] = hexColorToRGB(hexColorOrRedOrArray as ColorIntensity)
+    threshold = greenOrThreshold
   } else if (isRGB || isArray) {
-    [red, green, blue] = arrayOrRgbToRGB(hexColorOrRedOrArray as number | number[], green as number, blue as number)
+    [red, green, blue, threshold] = arrayOrRgbToRGB(hexColorOrRedOrArray as number | number[], greenOrThreshold as number, blue as number, threshold)
   } else {
@@ -58,3 +64,3 @@ // Not a color, respond with white color
 
-  return contrastFromHSP(red, green, blue)
+  return contrastFromHSP(red, green, blue, threshold)
 }
@@ -131,3 +137,3 @@
  * @param redOrArray The RGB array or the color red
- * @param green The color green
+ * @param greenOrThreshold The color green
  * @param blue The color blue
@@ -143,6 +149,7 @@ * @returns The array with the RGB values
  */
-function arrayOrRgbToRGB (redOrArray: number | number[], green?: number, blue?: number): [red: number, green: number, blue: number] {
+function arrayOrRgbToRGB (redOrArray: number | number[], greenOrThreshold?: number, blue?: number, threshold?: number): [red: number, green: number, blue: number, threshold: number] {
   let r = 0
   let g = 0
   let b = 0
+  let t = 0
   if (isArray) {
@@ -152,9 +159,11 @@ r = (redOrArray as number[])[0]
     b = (redOrArray as number[])[2]
+    t = greenOrThreshold as number
   } else if (isRGB) {
     r = redOrArray as number
-    g = green as number
+    g = greenOrThreshold as number
     b = blue as number
+    t = threshold as number
   }
 
-  return [r, g, b]
+  return [r, g, b, t]
 }
@@ -167,5 +176,6 @@
  * @param blue The color blue value
+ * @param threshold Contrast threshold to control the resulting font color, float values from 0 to 1. Default is 0.5.
  * @returns Black or White depending on the best possible contrast
  */
-function contrastFromHSP (red: number, green: number, blue: number): '#000000' | '#ffffff' {
+function contrastFromHSP (red: number, green: number, blue: number, threshold = 0.5): '#000000' | '#ffffff' {
   const pRed = 0.299
@@ -181,5 +191,5 @@ const pGreen = 0.587
 
-  return contrast > 0.5
+  return contrast > threshold
     ? '#000000'
     : '#ffffff'
 }

No alert changes

Improved metrics

Total package byte prevSize

1337937

increased by0.69%

Lines of code

1688

increased by1.99%

Number of lines in readme file

143

increased by34.91%

No dependency changes