@opndev/react-native-events 0.0.15 → 0.0.17

package/lib/hooks/use-json-api-data.js

@@ -0,0 +1,262 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { useEffect, useRef, useState } from 'react';
+
+function getByPath(obj, path) {
+  if (!path) return obj;
+  return path.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), obj);
+}
+
+const DEFAULT_REGULAR_MS = 15 * 60 * 1000;
+const cache = new Map();
+
+function getCacheKey(uri, bearerToken) {
+  return `${uri}::${bearerToken || ''}`;
+}
+
+function isFresh(entry, regularMs) {
+  if (!entry) return false;
+  return (Date.now() - entry.fetchedAt) < regularMs;
+}
+
+/**
+ * fetchJson
+ *
+ * Generic cached JSON fetch with bearer-token support. This is the
+ * same logic that used to live as news-specific `fetchNewsJson` —
+ * it was always fully generic underneath, just named after its
+ * first caller. Shares one in-memory cache across every caller,
+ * keyed by uri+bearerToken — two different widgets requesting the
+ * same uri within the TTL window share a single cached response
+ * rather than both fetching.
+ *
+ * @param {object} args
+ * @param {string} args.uri
+ * @param {string} [args.bearerToken]
+ * @param {boolean} [args.force] Bypass the cache for this call.
+ * @param {number} [args.regularMs] Defaults to 15 minutes.
+ *
+ * @returns {Promise<any>}
+ */
+export async function fetchJson({ uri, bearerToken, force = false, regularMs = DEFAULT_REGULAR_MS }) {
+  const key = getCacheKey(uri, bearerToken);
+  const entry = cache.get(key);
+
+  if (!force && isFresh(entry, regularMs)) {
+    return entry.data;
+  }
+
+  const headers = {};
+  if (bearerToken) {
+    headers.Authorization = `Bearer ${bearerToken}`;
+  }
+
+  const res = await fetch(uri, { method: 'GET', headers });
+
+  if (!res.ok) {
+    throw new Error(`Request failed (${res.status})`);
+  }
+
+  const data = await res.json();
+  cache.set(key, { data, fetchedAt: Date.now() });
+  return data;
+}
+
+/**
+ * clearJsonCache
+ *
+ * @param {object} args
+ * @param {string} args.uri
+ * @param {string} [args.bearerToken]
+ */
+export function clearJsonCache({ uri, bearerToken }) {
+  cache.delete(getCacheKey(uri, bearerToken));
+}
+
+async function defaultFetcher({ uri, bearerToken, force, regularMs }) {
+  return fetchJson({ uri, bearerToken, force, regularMs });
+}
+
+// ── Manual refresh cooldown ──────────────────────────────────
+// A second, separate tracker from the data cache above — this
+// governs "when is the refresh BUTTON allowed to be pressed again",
+// not "is the data stale". Shared per uri+bearerToken (same key
+// scheme as the data cache), so multiple widgets pointed at the
+// same endpoint share one cooldown rather than each tracking their
+// own independently.
+
+const MANUAL_LOCK_MS = 15 * 60 * 1000;
+const ERROR_REFRESH_MS = 5 * 60 * 1000;
+const cooldowns = new Map(); // key -> expiresAt timestamp
+
+function getCooldownRemaining(key) {
+  const expiresAt = cooldowns.get(key);
+  if (!expiresAt) return 0;
+  return Math.max(0, expiresAt - Date.now());
+}
+
+function setCooldown(key, durationMs) {
+  cooldowns.set(key, Date.now() + durationMs);
+}
+
+function clearCooldown(key) {
+  cooldowns.delete(key);
+}
+
+/**
+ * useJsonApiData
+ *
+ * Generic fetch + poll + reshape — the data-fetching half of what
+ * used to live inline inside NewsWidget, now reusable by any
+ * RemoteDataWidget-style component regardless of what it's actually
+ * fetching.
+ *
+ * Always returns the same shape:
+ *   { items, loading, error, refresh, manualRefresh, canManualRefresh }
+ *
+ * `refresh` is unchanged from before — exposed so a component can
+ * wire it into useImperativeHandle for an external
+ * ref.current.refresh() call (e.g. triggered by a push
+ * notification). It always works and is NOT subject to the
+ * cooldown below — a real notification shouldn't get silently
+ * dropped because someone tapped a refresh button five minutes ago.
+ *
+ * `manualRefresh` is new — meant for a UI refresh button. It
+ * respects a per-endpoint cooldown:
+ *   - succeeds → button locked for 15 minutes
+ *   - errors   → button locked for only 5 minutes (fail faster,
+ *                recover faster)
+ *   - whenever the automatic polling interval fires (success OR
+ *     error), the cooldown is cleared immediately — the data's
+ *     fresh either way, no reason to keep the button blocked.
+ * `canManualRefresh` reflects whether the button should currently
+ * be enabled.
+ *
+ * Caching behaviour (the underlying data, separate from the above):
+ * the initial load may reuse a fresh cached response. Interval
+ * ticks and any forced refresh always force a real fetch.
+ *
+ * @param {object} options
+ * @param {string} options.uri
+ * @param {string} [options.bearerToken]
+ * @param {string} [options.jpath] Dot-path to the array within the response (e.g. 'data.results'). Omit if the response IS the array.
+ * @param {(rawItem: any) => any} [options.mapItem] Reshapes each raw item into whatever the consuming widget expects. Defaults to identity (no reshaping).
+ * @param {number} [options.refreshIntervalMs] Polling interval. Defaults to 0 (no polling — fetch once on mount).
+ * @param {number} [options.regularMs] Cache freshness window, passed to the default fetcher. Defaults to 15 minutes.
+ * @param {number} [options.manualLockMs] Defaults to 15 minutes.
+ * @param {number} [options.errorRefreshMs] Defaults to 5 minutes.
+ * @param {(args: { uri: string, bearerToken?: string, force: boolean }) => Promise<any>} [options.fetcher] Defaults to the cached fetchJson above.
+ *
+ * @returns {{ items: any[], loading: boolean, error: string|null, refresh: () => Promise<void>, manualRefresh: () => Promise<void>, canManualRefresh: boolean }}
+ */
+export function useJsonApiData({
+  uri,
+  bearerToken,
+  jpath,
+  mapItem = (item) => item,
+  refreshIntervalMs = 0,
+  regularMs,
+  fetcher = defaultFetcher,
+  manualLockMs = MANUAL_LOCK_MS,
+  errorRefreshMs = ERROR_REFRESH_MS,
+}) {
+  const [items, setItems] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const intervalRef = useRef(null);
+  const cooldownTimeoutRef = useRef(null);
+
+  const cooldownKey = getCacheKey(uri, bearerToken);
+
+  const [canManualRefresh, setCanManualRefresh] = useState(
+    () => getCooldownRemaining(cooldownKey) <= 0
+  );
+
+  function applyCooldown(durationMs) {
+    setCooldown(cooldownKey, durationMs);
+    setCanManualRefresh(false);
+
+    if (cooldownTimeoutRef.current) {
+      clearTimeout(cooldownTimeoutRef.current);
+    }
+    cooldownTimeoutRef.current = setTimeout(() => {
+      setCanManualRefresh(true);
+    }, durationMs);
+  }
+
+  function releaseCooldown() {
+    clearCooldown(cooldownKey);
+    if (cooldownTimeoutRef.current) {
+      clearTimeout(cooldownTimeoutRef.current);
+      cooldownTimeoutRef.current = null;
+    }
+    setCanManualRefresh(true);
+  }
+
+  async function load(force = false, source = 'initial') {
+    setError(null);
+    let succeeded = true;
+
+    try {
+      const raw = await fetcher({ uri, bearerToken, force, regularMs });
+      const resolved = getByPath(raw, jpath);
+
+      if (!Array.isArray(resolved)) {
+        console.warn(
+          jpath
+            ? `useJsonApiData: jpath "${jpath}" did not resolve to an array (got ${typeof resolved}). Check that this path actually points at the array in your API's response. Falling back to an empty list.`
+            : `useJsonApiData: expected the response to be an array, but got ${typeof resolved}. If your API wraps the array in an object (e.g. { items: [...] }), pass jpath to point at it (e.g. jpath="items"). Falling back to an empty list.`
+        );
+      }
+
+      setItems(Array.isArray(resolved) ? resolved.map(mapItem) : []);
+    }
+    catch (e) {
+      succeeded = false;
+      setError(e.message || 'Unable to load data.');
+    }
+
+    setLoading(false);
+
+    if (source === 'manual') {
+      applyCooldown(succeeded ? manualLockMs : errorRefreshMs);
+    }
+    else if (source === 'system') {
+      releaseCooldown();
+    }
+  }
+
+  useEffect(() => {
+    setLoading(true);
+    setCanManualRefresh(getCooldownRemaining(cooldownKey) <= 0);
+    load(false, 'initial');
+
+    if (refreshIntervalMs > 0) {
+      intervalRef.current = setInterval(() => load(true, 'system'), refreshIntervalMs);
+      return () => clearInterval(intervalRef.current);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [uri, bearerToken, jpath, refreshIntervalMs]);
+
+  useEffect(() => {
+    return () => {
+      if (cooldownTimeoutRef.current) {
+        clearTimeout(cooldownTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    items,
+    loading,
+    error,
+    refresh: () => load(true, 'external'),
+    manualRefresh: () => {
+      if (getCooldownRemaining(cooldownKey) > 0) return;
+      load(true, 'manual');
+    },
+    canManualRefresh,
+  };
+}

package/lib/hooks/use-panel-contrast.js

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * PanelContrastContext
+ *
+ * Provided by Panel — the contrast color automatically derived from
+ * its backgroundColor (or a manual override, if Panel was given
+ * one). Defaults to null, so anything reading this outside a Panel
+ * just gets "no opinion," not a wrong color.
+ */
+export const PanelContrastContext = createContext(null);
+
+/**
+ * usePanelContrast
+ *
+ * @returns {string|null} The enclosing Panel's contrast color, or null if there isn't one.
+ */
+export function usePanelContrast() {
+  return useContext(PanelContrastContext);
+}

package/lib/hooks/use-static-data.js

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+/**
+ * useStaticData
+ *
+ * The "I already have this data" counterpart to useJsonApiData —
+ * same returned shape, so DataListWidget (or anything else
+ * consuming either hook) never needs to know which one it's
+ * actually talking to. No fetch, no polling, no cache, no manual
+ * refresh — there's nothing to refresh; the data only changes if
+ * the caller passes different `data` on a re-render.
+ *
+ * @param {object} options
+ * @param {any[]} options.data
+ * @param {(rawItem: any) => any} [options.mapItem] Reshapes each raw item into whatever the consuming widget expects. Defaults to identity (no reshaping).
+ *
+ * @returns {{ items: any[], loading: false, error: null, refresh: () => void, manualRefresh: () => void, canManualRefresh: false }}
+ */
+export function useStaticData({ data, mapItem = (item) => item }) {
+  const items = (data || []).map(mapItem);
+
+  return {
+    items,
+    loading: false,
+    error: null,
+    refresh: () => {},
+    manualRefresh: () => {},
+    canManualRefresh: false,
+  };
+}

package/lib/index.js

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 
-const VERSION = "0.0.15";
+const VERSION = "0.0.17";
 
 // TODO: @opndev/util?
 export { formatPrice } from './utils/format-price.js';

package/lib/utils/colors.js

@@ -18,19 +18,15 @@
 export function mixHexColors(a, b, amount = 0.5) {
   const ah = a.replace('#', '');
   const bh = b.replace('#', '');
-
   const ar = parseInt(ah.slice(0, 2), 16);
   const ag = parseInt(ah.slice(2, 4), 16);
   const ab = parseInt(ah.slice(4, 6), 16);
-
   const br = parseInt(bh.slice(0, 2), 16);
   const bg = parseInt(bh.slice(2, 4), 16);
   const bb = parseInt(bh.slice(4, 6), 16);
-
   const r = Math.round(ar + (br - ar) * amount);
   const g = Math.round(ag + (bg - ag) * amount);
   const b2 = Math.round(ab + (bb - ab) * amount);
-
   return (
     '#' +
     r.toString(16).padStart(2, '0') +
@@ -40,27 +36,116 @@ export function mixHexColors(a, b, amount = 0.5) {
 }
 
 /**
- * Return black or white depending on which has better contrast.
+ * Convert a hex color to HSL.
+ *
+ * @param {string} hex
+ *   Color as "#rrggbb".
+ *
+ * @returns {{h: number, s: number, l: number}}
+ *   Each in the 0-1 range (h is fraction of 360°, not degrees).
+ */
+function hexToHsl(hex) {
+  const value = hex.replace('#', '');
+  const r = parseInt(value.slice(0, 2), 16) / 255;
+  const g = parseInt(value.slice(2, 4), 16) / 255;
+  const b = parseInt(value.slice(4, 6), 16) / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+
+  let h = 0;
+  let s = 0;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+    switch (max) {
+      case r:
+        h = (g - b) / d + (g < b ? 6 : 0);
+        break;
+      case g:
+        h = (b - r) / d + 2;
+        break;
+      default:
+        h = (r - g) / d + 4;
+        break;
+    }
+    h /= 6;
+  }
+
+  return { h, s, l };
+}
+
+/**
+ * Convert HSL back to a hex color.
+ *
+ * @param {{h: number, s: number, l: number}} hsl
+ *   Each in the 0-1 range (h is fraction of 360°, not degrees).
+ *
+ * @returns {string}
+ *   Color as "#rrggbb".
+ */
+function hslToHex({ h, s, l }) {
+  function hueToRgb(p, q, t) {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  }
+
+  let r;
+  let g;
+  let b;
+
+  if (s === 0) {
+    r = g = b = l;
+  }
+  else {
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    r = hueToRgb(p, q, h + 1 / 3);
+    g = hueToRgb(p, q, h);
+    b = hueToRgb(p, q, h - 1 / 3);
+  }
+
+  const toHex = (c) => Math.round(c * 255).toString(16).padStart(2, '0');
+  return '#' + toHex(r) + toHex(g) + toHex(b);
+}
+
+/**
+ * Return a contrasting color in the SAME hue/saturation family as
+ * the input, just pushed to a very different lightness — the same
+ * technique CSS color-ramp design systems use (Tailwind/Radix-style
+ * 50-950 scales): same color family, different shade, rather than
+ * jumping to flat black/white. A light, desaturated input still
+ * gets a colored (just very dark) result; a fully neutral input
+ * (pure white/black/gray, s=0) naturally falls back to plain
+ * gray at the target lightness, since there's no hue to preserve.
  *
  * @param {string} hex
  *   Background color as "#rrggbb".
  *
  * @returns {string}
- *   "#000000" or "#ffffff".
+ *   A same-hue, contrasting-lightness hex color.
  */
 export function contrastColor(hex) {
   const value = hex.replace('#', '');
-
   const r = parseInt(value.slice(0, 2), 16) / 255;
   const g = parseInt(value.slice(2, 4), 16) / 255;
   const b = parseInt(value.slice(4, 6), 16) / 255;
-
   const luminance =
     0.2126 * toLinear(r) +
     0.7152 * toLinear(g) +
     0.0722 * toLinear(b);
 
-  return luminance > 0.179 ? '#000000' : '#ffffff';
+  const { h, s } = hexToHsl(hex);
+  const targetLightness = luminance > 0.179 ? 0.15 : 0.92;
+
+  return hslToHex({ h, s, l: targetLightness });
 }
 
 /**
@@ -76,7 +161,5 @@ export function toLinear(channel) {
   if (channel <= 0.03928) {
     return channel / 12.92;
   }
-
   return ((channel + 0.055) / 1.055) ** 2.4;
 }
-

package/lib/widgets/data-list-widget.jsx

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import {
+  ActivityIndicator,
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
+import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
+import { usePanelContrast } from '../hooks/use-panel-contrast';
+
+const defaultStyle = StyleSheet.create({
+  container: {
+    gap: 8,
+  },
+  titleRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  title: {
+    fontWeight: '700',
+  },
+  refreshButton: {
+    padding: 4,
+  },
+  divider: {
+    height: 3,
+    backgroundColor: 'rgba(0,0,0,0.15)',
+    marginTop: 4,
+    marginBottom: 4,
+  },
+  item: {
+    flexDirection: 'row',
+    gap: 8,
+  },
+  bullet: {
+    opacity: 0.6,
+  },
+  itemBody: {
+    flex: 1,
+    gap: 2,
+  },
+});
+
+/**
+ * DataListWidget
+ *
+ * The actual "title + divider + bullet list (+ optional second
+ * line) + refresh button" rendering — shared by RemoteDataWidget
+ * and StaticDataWidget, which differ only in WHERE `items` comes
+ * from (a polled API vs. data you already have). Neither of those
+ * two components renders anything of its own; both just call a
+ * data hook and hand the result to this component.
+ *
+ * Not meant to be used directly in app code — it has no data
+ * source of its own. Use RemoteDataWidget or StaticDataWidget.
+ *
+ * @param {object} props
+ * @param {Array<{id: any, title: string, description?: string}>} props.items
+ * @param {boolean} props.loading
+ * @param {string|null} props.error
+ * @param {Function} [props.manualRefresh]
+ * @param {boolean} [props.canManualRefresh]
+ * @param {string} [props.title] Defaults to null (no heading shown).
+ * @param {boolean} [props.showDivider] Defaults to true. Ignored if title is falsy.
+ * @param {object} [props.dividerStyle]
+ * @param {boolean} [props.showRefreshButton] Defaults to true.
+ * @param {boolean} [props.showBullet] Defaults to true.
+ * @param {string} [props.refreshIconColor] Defaults to '#000'.
+ * @param {string} [props.refreshIconDisabledColor] Color while on cooldown. Defaults to 'rgba(0,0,0,0.3)'.
+ * @param {React.ComponentType} [props.TextComponent] Defaults to Text.
+ * @param {Function} [props.onPressItem]
+ * @param {string} [props.emptyLabel] Defaults to 'No items.'
+ * @param {string} [props.errorLabel] Defaults to 'Unable to load data.'
+ * @param {object} [props.containerStyle]
+ * @param {object} [props.titleStyle]
+ * @param {object} [props.itemStyle]
+ * @param {object} [props.itemTextStyle]
+ * @param {object} [props.descriptionStyle]
+ * @param {object} [props.errorTextStyle]
+ *
+ * @returns {JSX.Element}
+ */
+export default function DataListWidget({
+  items,
+  loading,
+  error,
+  manualRefresh,
+  canManualRefresh,
+
+  title = null,
+  showDivider = true,
+  dividerStyle,
+  showRefreshButton = true,
+  showBullet = true,
+  refreshIconColor = '#000',
+  refreshIconDisabledColor = 'rgba(0,0,0,0.3)',
+  TextComponent = Text,
+  onPressItem,
+
+  emptyLabel = 'No items.',
+  errorLabel = 'Unable to load data.',
+
+  containerStyle,
+  titleStyle,
+  itemStyle,
+  itemTextStyle,
+  descriptionStyle,
+  errorTextStyle,
+}) {
+  const showTitleRow = title || showRefreshButton;
+  const panelContrast = usePanelContrast();
+  const contrastTextStyle = panelContrast ? { color: panelContrast } : null;
+
+  if (__DEV__ && !loading && !error && items.length) {
+    items.forEach((item, index) => {
+      if (item == null || item.id == null || item.title == null) {
+        throw new Error(
+          `DataListWidget: item at index ${index} is missing "id" or "title". ` +
+          `Check that mapItem returns { id, title, description? } — got: ${JSON.stringify(item)}`
+        );
+      }
+    });
+  }
+
+  return (
+    <View
+      style={[
+        defaultStyle.container,
+        containerStyle,
+      ]}
+    >
+      {showTitleRow ? (
+        <View
+          style={[
+            defaultStyle.titleRow,
+            { justifyContent: title ? 'space-between' : 'flex-end' },
+          ]}
+        >
+          {title ? (
+            <TextComponent style={[defaultStyle.title, contrastTextStyle, titleStyle]}>
+              {title}
+            </TextComponent>
+          ) : null}
+
+          {showRefreshButton ? (
+            <Pressable
+              onPress={manualRefresh}
+              disabled={!canManualRefresh}
+              style={defaultStyle.refreshButton}
+            >
+              <MaterialCommunityIcons
+                name="refresh"
+                size={18}
+                color={canManualRefresh ? refreshIconColor : refreshIconDisabledColor}
+              />
+            </Pressable>
+          ) : null}
+        </View>
+      ) : null}
+
+      {title && showDivider ? (
+        <View style={[defaultStyle.divider, dividerStyle]} />
+      ) : null}
+
+      {loading ? <ActivityIndicator /> : null}
+
+      {!loading && error ? (
+        <TextComponent style={errorTextStyle}>{error || errorLabel}</TextComponent>
+      ) : null}
+
+      {!loading && !error && !items.length ? (
+        <TextComponent style={errorTextStyle}>{emptyLabel}</TextComponent>
+      ) : null}
+
+      {!loading && !error && items.map((item) => (
+        <Pressable
+          key={item.id}
+          style={[defaultStyle.item, itemStyle]}
+          onPress={() => onPressItem?.(item)}
+        >
+          {showBullet ? (
+            <TextComponent style={[defaultStyle.bullet, contrastTextStyle, itemTextStyle]}>{'\u2022'}</TextComponent>
+          ) : null}
+          <View style={defaultStyle.itemBody}>
+            <TextComponent style={[contrastTextStyle, itemTextStyle]}>
+              {item.title}
+            </TextComponent>
+            {item.description ? (
+              <TextComponent style={[contrastTextStyle, descriptionStyle]}>
+                {item.description}
+              </TextComponent>
+            ) : null}
+          </View>
+        </Pressable>
+      ))}
+    </View>
+  );
+}