support high-contrast detection, fixes #424

ibm-js · Sep 9, 2015 · 018f49a · 018f49a
1 parent 5b1e978
commit 018f49a
Show file tree

Hide file tree

Showing 4 changed files with 130 additions and 0 deletions.
diff --git a/docs/hc.md b/docs/hc.md
@@ -0,0 +1,42 @@
+---
+layout: doc
+title: delite/hc
+---
+
+# delite/hc
+
+Provides "High Contrast" feature detection for accessibility purposes.
+
+This is useful for Internet Explorer and Firefox running on Windows.
+It doesn't apply to Chrome or Safari (on mobile, mac, or desktop), which don't support high contrast mode.
+
+## Introduction
+
+By doing a `require()` of `delite/hc`,  `delite/hc` will set the `has("highcontrast")` flag
+so code can check directly whether or not it is in high contrast mode and branch appropriately.
+If the machine is in high contrast mode, `has("highcontrast")` is the text color being used by the browser
+(that overrides the text color defined in CSS rules).
+
+
+`delite/hc` will also add the `d-hc` CSS class to your document's `<body>` tag  if the machine is in high contrast mode.
+
+Normally this module should not be used.  As long as widgets and applications avoid using background images for
+icons, the browser will do everything for high contrast mode automatically.  The exception is for SVG,
+which the browser does not adjust.
+
+
+## Usage
+
+Simply require the module, and then reference `has("highcontrast")`:
+
+
+```js
+require (["delite/hc", ...), function (has, ...) {
+    ...
+    var hcColor = has("highcontrast");
+    if (hcColor) {
+       mySvgNode.style.color = hcColor;
+    }
+});
+```
+
diff --git a/docs/index.md b/docs/index.md
@@ -35,6 +35,7 @@ Specifically, it's based on the following concepts:
 * [a11y](a11y.md) - accessibility utility functions
 * [a11yclick](a11yclick.md) - allow keyboard "click" (via ENTER or SPACE) on custom DOM nodes
 * [handlebars!](handlebars.md) - plugin to compile reactive templates for use in widgets
+* [hc!](hc.md) - tests if OS is in high contrast mode
 * [place](place.md) - low level module for placing a popup or dropdown at a certain position
 * [popup](popup.md) - popup manager
 * [register](register.md) - utility module for declaring new custom element types

diff --git a/hc.js b/hc.js
@@ -0,0 +1,51 @@
+/**
+ * Test if computer is in high contrast mode (i.e. if CSS color settings are ignored)
+ * Defines `has("highcontrast")` and sets `d-hc` CSS class on `<body>` if machine is in high contrast mode.
+ *
+ * Normally this code should not be used.  As long as widgets or applications avoid using background images for
+ * icons, the browser will do everything for high contrast mode automatically.  The exception is for SVG,
+ * which the browser does not adjust.
+ *
+ * If the OS is in high contrast mode and the browser obeys the OS setting,
+ * `has("highcontrast")` is the color that text appears as.  Otherwise, `has("highcontrast")` is null.
+ *
+ * Module returns `has()` method.
+ *
+ * @module delite/hc
+ */
+define([
+	"requirejs-dplugins/has",
+	"requirejs-domready/domReady!"
+], function (has) {
+
+	has.add("highcontrast", function () {
+		if (typeof window === "undefined") {
+			return false;
+		}
+
+		// note: if multiple documents, doesn't matter which one we use
+		var div = document.createElement("div");
+		try {
+			div.style.cssText =
+				"border: 1px solid; border-color:red green; position: absolute; height: 5px; top: -999px;";
+			document.body.appendChild(div);
+
+			var cs = getComputedStyle(div);
+
+			// If it's high contrast mode then return the color and background color the browser is using.
+			// Otherwise just return null
+			return cs.borderTopColor === cs.borderRightColor ? cs.color : null;
+		} catch (e) {
+			console.warn("hccss: exception detecting high-contrast mode, document is likely hidden: " + e.toString());
+			return null;
+		} finally {
+			document.body.removeChild(div);
+		}
+	});
+
+	if (has("highcontrast")) {
+		document.body.className = (document.body.className + " d-hc").trim();
+	}
+
+	return has;
+});
diff --git a/tests/functional/hc.html b/tests/functional/hc.html
@@ -0,0 +1,36 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+	<title>high contrast detection test</title>
+	<script type="text/javascript" src="boilerplate.js"></script>
+	<script language="JavaScript" type="text/javascript">
+		require([
+			"delite/hc",
+			"requirejs-domready/domReady!"
+		], function (has) {
+			if (has("highcontrast")) {
+				result.innerHTML = "High contrast mode detected, text color = " + has("highcontrast");
+			} else {
+				result.innerHTML = "Not high contrast mode (or browser ignores OS high contrast mode setting)";
+			}
+		})
+	</script>
+</head>
+<body>
+<h1>High Contrast Detection Test</h1>
+<p>
+	Result: <span id="result"></span>.
+</p>
+<p>
+	On Windows, setting the OS to high-contrast mode will make IE and FF ignore the CSS settings for
+	text color and size, and use the OS's settings instead (typically white on black or black on white).
+	Note that on Chrome, the OS setting is ignored.
+</p>
+<p>
+	Text with CSS settings for color:
+	<span style="color: red">red</span>
+	<span style="color: green">green</span>
+	<span style="color: blue">blue</span>
+</p>
+</body>
+</html>