@screenly/edge-apps 1.3.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
@@ -140,12 +144,90 @@ signalReady()
 - `addUTMParams(url, params?)` - Add UTM parameters to URL
 - `addUTMParamsIf(url, enabled, params?)` - Conditionally add UTM parameters
 
+### Edge App Cache
+
+- `readEdgeAppCache(namespace, key)` - Read a `localStorage`-backed, namespaced last-known-good value
+- `writeEdgeAppCache(namespace, key, value)` - Write a `localStorage`-backed, namespaced last-known-good value
+
 ### Error Reporting (Sentry)
 
 - `setupSentry(app, contexts?)` - Initialize Sentry using the `sentry_dsn` setting; sets the `edge_app` tag, hostname, and any additional contexts. No-ops if `sentry_dsn` is not configured.
 - `scrubSensitiveData(event)` - Sentry `beforeSend` hook that redacts values of settings keys matching `token`, `secret`, `password`, or `credential` with `[REDACTED]`. Drops the event if it cannot be safely serialized.
 - `reportError(error, context?)` - Capture an exception via Sentry with optional extra context.
 
+## Edge App Cache
+
+When an Edge App fetches data from a backend, a failure shouldn't necessarily
+break the display — falling back to the last-known-good value is often better
+than showing an error.
+
+### `readEdgeAppCache(namespace, key)` / `writeEdgeAppCache(namespace, key, value)`
+
+Read/write a `localStorage`-backed value under `namespace`, so different
+apps/caches don't collide. There is no TTL: it's meant to store the
+last-known-good value and be consulted only after a genuine fetch failure, not
+as a general-purpose expiring cache — and `localStorage` itself isn't
+guaranteed to survive a device reboot. Both fail silently (return `null` /
+no-op) if storage is unavailable, disabled, or full — so it's safe to use
+without extra error handling around it.
+
+`writeEdgeAppCache()` accepts any JSON-serializable value (object, array,
+string, number, etc.) — `WeatherData` below is just a stand-in name for
+"whatever your fetch returns," not a type this library exports.
+
+```typescript
+import {
+  readEdgeAppCache,
+  writeEdgeAppCache,
+  getSettingWithDefault,
+} from '@screenly/edge-apps'
+
+async function loadWeather() {
+  const displayErrors = getSettingWithDefault('display_errors', false)
+
+  try {
+    const response = await fetch(weatherApiUrl)
+    if (!response.ok) throw new Error(`Weather API returned ${response.status}`)
+
+    // weatherData can be any JSON-serializable shape, e.g.:
+    // { temperature: 18, description: 'Cloudy', unit: 'metric' }
+    const weatherData: WeatherData = await response.json()
+    writeEdgeAppCache('my-edge-app', 'weather', weatherData)
+    return weatherData
+  } catch (error) {
+    // When `display_errors` is on, the raw error always wins, by design, so
+    // operators can diagnose real problems instead of seeing stale data.
+    if (!displayErrors) {
+      return readEdgeAppCache<WeatherData>('my-edge-app', 'weather')
+    }
+    throw error
+  }
+}
+```
+
+## 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/edge-app-cache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads and JSON-parses the value stored under `${namespace}:${key}` in
+ * `localStorage`, or `null` if missing, unreadable, or storage is
+ * unavailable. Meant for last-known-good fallback data for Edge Apps:
+ * consult it only after a genuine fetch failure, not as a general-purpose
+ * expiring cache — there is no TTL, and `localStorage` itself isn't
+ * guaranteed to survive a device reboot.
+ */
+export declare function readEdgeAppCache<T>(namespace: string, key: string): T | null;
+/**
+ * JSON-serializes and stores `value` under `${namespace}:${key}` in
+ * `localStorage`. Fails silently if storage is unavailable, disabled, or
+ * full.
+ */
+export declare function writeEdgeAppCache(namespace: string, key: string, value: unknown): void;
+//# sourceMappingURL=edge-app-cache.d.ts.map

package/dist/utils/edge-app-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-app-cache.d.ts","sourceRoot":"","sources":["../../src/utils/edge-app-cache.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAU5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,IAAI,CAWN"}

package/dist/utils/edge-app-cache.js

@@ -0,0 +1,49 @@
+function getStorage() {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        return localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads and JSON-parses the value stored under `${namespace}:${key}` in
+ * `localStorage`, or `null` if missing, unreadable, or storage is
+ * unavailable. Meant for last-known-good fallback data for Edge Apps:
+ * consult it only after a genuine fetch failure, not as a general-purpose
+ * expiring cache — there is no TTL, and `localStorage` itself isn't
+ * guaranteed to survive a device reboot.
+ */
+export function readEdgeAppCache(namespace, key) {
+    const storage = getStorage();
+    if (!storage)
+        return null;
+    try {
+        const raw = storage.getItem(`${namespace}:${key}`);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * JSON-serializes and stores `value` under `${namespace}:${key}` in
+ * `localStorage`. Fails silently if storage is unavailable, disabled, or
+ * full.
+ */
+export function writeEdgeAppCache(namespace, key, value) {
+    const storage = getStorage();
+    if (!storage)
+        return;
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            return;
+        storage.setItem(`${namespace}:${key}`, serialized);
+    }
+    catch {
+        // Storage disabled or quota exceeded; caller simply has nothing cached.
+    }
+}

package/dist/utils/index.d.ts

@@ -1,5 +1,7 @@
 export * from './calendar.js';
+export * from './color.js';
 export * from './error-handling.js';
+export * from './edge-app-cache.js';
 export * from './html.js';
 export * from './theme.js';
 export * from './locale.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,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,5 +1,7 @@
 export * from './calendar.js';
+export * from './color.js';
 export * from './error-handling.js';
+export * from './edge-app-cache.js';
 export * from './html.js';
 export * from './theme.js';
 export * from './locale.js';

package/package.json

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