@screenly/edge-apps 1.4.0 → 1.5.0

package/README.md

@@ -105,6 +105,10 @@ signalReady()
 - `setupBrandingLogo()` - Fetch and process branding logo
 - `setupBranding()` - Setup complete branding (colors and logo)
 
+### Color
+
+- `isLightColor(color)` - Check whether a color needs dark text on top of it
+
 ### Settings
 
 - `getSettings()` - Get all settings
@@ -201,6 +205,29 @@ async function loadWeather() {
 }
 ```
 
+## Color Contrast
+
+Customers supply their own accent color through `screenly_color_accent`, so an
+app that paints anything on top of it cannot hardcode the text color. A pale
+brand needs dark text, a deep one needs light text.
+
+`isLightColor()` answers that question using the WCAG relative luminance
+formula, so hues are ranked the way an eye ranks them rather than by averaging
+raw channels. Pure yellow and pure blue have similar RGB totals but land on
+opposite sides of the threshold.
+
+```typescript
+import { isLightColor, setupTheme } from '@screenly/edge-apps'
+
+const { primary } = setupTheme()
+document.body.classList.toggle('on-light-brand', isLightColor(primary))
+```
+
+It accepts hex (`#abc`, `#aabbcc`, `#aabbccdd`) and numeric `rgb()` / `rgba()`
+strings, ignoring any alpha. Percentage channels and named colors are not
+supported. Anything it cannot parse returns `false`, so a malformed setting
+leaves an unattended screen rendering instead of throwing.
+
 ## Web Components
 
 This library includes reusable web components for building consistent Edge Apps. See the [components documentation](https://github.com/Screenly/edge-apps-library/blob/main/docs/components.md) for usage details.

package/dist/utils/color.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check whether a color is light enough to need dark text on top of it.
+ *
+ * Uses the WCAG relative luminance formula rather than raw RGB averages, so
+ * hues of the same nominal brightness are ranked the way an eye ranks them.
+ * Accepts hex (`#abc`, `#aabbcc`, `#aabbccdd`) and numeric `rgb()` / `rgba()`
+ * strings; any alpha component is ignored. Percentage channels and named
+ * colors are not supported.
+ *
+ * Returns `false` for values it cannot parse, so an unattended screen keeps
+ * rendering instead of throwing on a malformed setting.
+ */
+export declare function isLightColor(color: string): boolean;
+//# sourceMappingURL=color.d.ts.map

package/dist/utils/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/utils/color.ts"],"names":[],"mappings":"AAkEA;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKnD"}

package/dist/utils/color.js

@@ -0,0 +1,72 @@
+/**
+ * Relative luminance at which text contrast against black and against white
+ * is equal. Colors above it read better with dark text, colors below it with
+ * light text.
+ */
+const LIGHT_THRESHOLD = 0.179;
+function clampChannel(value) {
+    return Math.min(255, Math.max(0, value));
+}
+function parseHex(color) {
+    const digits = color.slice(1);
+    const expanded = digits.length === 3 || digits.length === 4
+        ? digits.replace(/./g, (digit) => digit + digit)
+        : digits;
+    if (expanded.length !== 6 && expanded.length !== 8)
+        return null;
+    if (!/^[0-9a-f]+$/i.test(expanded))
+        return null;
+    return [
+        parseInt(expanded.slice(0, 2), 16),
+        parseInt(expanded.slice(2, 4), 16),
+        parseInt(expanded.slice(4, 6), 16),
+    ];
+}
+function parseRgb(color) {
+    const match = color.match(/^rgba?\(([^)]+)\)$/i);
+    if (!match)
+        return null;
+    const channels = match[1]
+        .split(/[\s,/]+/)
+        .filter(Boolean)
+        .slice(0, 3)
+        .map(Number);
+    if (channels.length !== 3 || channels.some(Number.isNaN))
+        return null;
+    return [
+        clampChannel(channels[0]),
+        clampChannel(channels[1]),
+        clampChannel(channels[2]),
+    ];
+}
+function parseColor(color) {
+    const value = color.trim();
+    if (value.startsWith('#'))
+        return parseHex(value);
+    return parseRgb(value);
+}
+function toLinear(channel) {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+function getRelativeLuminance([red, green, blue]) {
+    return (0.2126 * toLinear(red) + 0.7152 * toLinear(green) + 0.0722 * toLinear(blue));
+}
+/**
+ * Check whether a color is light enough to need dark text on top of it.
+ *
+ * Uses the WCAG relative luminance formula rather than raw RGB averages, so
+ * hues of the same nominal brightness are ranked the way an eye ranks them.
+ * Accepts hex (`#abc`, `#aabbcc`, `#aabbccdd`) and numeric `rgb()` / `rgba()`
+ * strings; any alpha component is ignored. Percentage channels and named
+ * colors are not supported.
+ *
+ * Returns `false` for values it cannot parse, so an unattended screen keeps
+ * rendering instead of throwing on a malformed setting.
+ */
+export function isLightColor(color) {
+    const rgb = parseColor(color);
+    if (!rgb)
+        return false;
+    return getRelativeLuminance(rgb) > LIGHT_THRESHOLD;
+}

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './calendar.js';
+export * from './color.js';
 export * from './error-handling.js';
 export * from './edge-app-cache.js';
 export * from './html.js';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}

package/dist/utils/index.js

@@ -1,4 +1,5 @@
 export * from './calendar.js';
+export * from './color.js';
 export * from './error-handling.js';
 export * from './edge-app-cache.js';
 export * from './html.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@screenly/edge-apps",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A TypeScript library for interfacing with Screenly Edge Apps API",
   "type": "module",
   "sideEffects": [