@opndev/react-native-events 0.0.15 → 0.0.16

package/Changes

@@ -1,5 +1,12 @@
 Revision history for @opndev/opndev-react-native-events
 
+0.0.16       2026-06-27 23:25:11Z
+
+  * Add widgets for dynamic and static content:
+    news now is dynamic and some other bits are static because we don't need to
+    do call to a backend to decide what scheduling or rules there are. Offline
+    mode is cool too
+
 0.0.15       2026-06-26 22:56:26Z
 
   * Add debugRouteState() to debug export to debug route states more easily

package/README.md

@@ -5,7 +5,7 @@ SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
 SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 -->
 
-# Welcome to @opndev/opndev-react-native-events
+# Welcome to @opndev/react-native-events
 
 Reusable React Native / Expo components for event-style apps.
 
@@ -26,7 +26,7 @@ This package provides a small set of building blocks for:
 ## Installation
 
 ```bash
-npm install @opndev/opndev-react-native-events
+npm install @opndev/react-native-events
 ```
 
 Peer dependencies are expected to be installed by the consuming app.

package/lib/actions/news.js

@@ -2,99 +2,21 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 
-/**
- * News API cache time-to-live.
- */
-const TTL_MS = 15 * 60 * 1000;
-
-/**
- * In-memory cache for news API responses.
- */
-const cache = new Map();
-
-/**
- * Builds a cache key for a given URI and bearer token.
- *
- * @param {string} uri
- * @param {string} [bearerToken]
- *
- * @returns {string}
- */
-function getCacheKey(uri, bearerToken) {
-  return `${uri}::${bearerToken || ''}`;
-}
-
-/**
- * Returns true when a cache entry is still fresh.
- *
- * @param {object} entry
- *
- * @returns {boolean}
- */
-function isFresh(entry) {
-  if (!entry) {
-    return false;
-  }
-
-  return (Date.now() - entry.fetchedAt) < TTL_MS;
-}
-
-/**
- * Fetches JSON from the news API with optional bearer token support.
- *
- * Cached responses are reused for 15 minutes unless `force` is set.
- *
- * @param {object} args
- * @param {string} args.uri
- * @param {string} [args.bearerToken]
- * @param {boolean} [args.force]
- *
- * @returns {Promise<any>}
- */
-export async function fetchNewsJson({
-  uri,
-  bearerToken,
-  force = false,
-}) {
-  const key = getCacheKey(uri, bearerToken);
-  const entry = cache.get(key);
-
-  if (!force && isFresh(entry)) {
-    return entry.data;
-  }
-
-  const headers = {};
-  if (bearerToken) {
-    headers.Authorization = `Bearer ${bearerToken}`;
-  }
-
-  const res = await fetch(uri, {
-    method: 'GET',
-    headers,
-  });
-
-  const data = await res.json();
-
-  cache.set(key, {
-    data,
-    fetchedAt: Date.now(),
-  });
-
-  return data;
+// This used to be its own standalone cache implementation. The
+// logic was always fully generic underneath (just a TTL cache
+// around fetch + bearer auth) — it's been moved to
+// @opndev/react-native-events as useJsonApiData's default fetcher,
+// shared with RemoteDataWidget. This file now just re-exports under
+// the original names so NewsListScreen/NewsItemScreen don't need to
+// change, and there's only one actual cache implementation rather
+// than two that could drift apart.
+
+import { fetchJson, clearJsonCache } from '@opndev/react-native-events/widgets';
+
+export function fetchNewsJson({ uri, bearerToken, force }) {
+  return fetchJson({ uri, bearerToken, force });
 }
 
-/**
- * Clears the cached response for a specific URI.
- *
- * @param {object} args
- * @param {string} args.uri
- * @param {string} [args.bearerToken]
- *
- * @returns {void}
- */
-export function clearNewsCache({
-  uri,
-  bearerToken,
-}) {
-  cache.delete(getCacheKey(uri, bearerToken));
+export function clearNewsCache({ uri, bearerToken }) {
+  return clearJsonCache({ uri, bearerToken });
 }

package/lib/components/hero-screen-header.jsx

@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
 import { useState, isValidElement, Children } from 'react';
 import { View, Image, Pressable, StyleSheet } from 'react-native';
 import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';

package/lib/components/schedule.jsx

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { View, Text, StyleSheet } from 'react-native';
+import Panel from './panel';
+
+const defaultStyle = StyleSheet.create({
+  container: {
+    gap: 16,
+  },
+  dayHeading: {
+    fontWeight: '700',
+    marginBottom: 8,
+  },
+  event: {
+    gap: 4,
+    marginBottom: 12,
+  },
+  eventTitle: {
+    fontWeight: '700',
+  },
+});
+
+/**
+ * Schedule
+ *
+ * Renders a multi-day event schedule — one Panel per day. Panels
+ * cycle through `washColors` in order (e.g. [primarySoft,
+ * secondarySoft] gives primary/secondary/primary/secondary...), so
+ * consecutive days are visually distinct without any per-day
+ * configuration needed.
+ *
+ * @param {object} props
+ * @param {object} props.schedule Shape: { [dateKey]: Array<{ event: string, description?: string }> }
+ * @param {string[]} [props.washColors] Colors cycled through per day, in order. Omit for no alternation (every Panel uses Panel's own default).
+ * @param {(dateKey: string) => string} [props.formatDate] Defaults to showing the raw key as-is.
+ * @param {React.ComponentType} [props.TextComponent] Defaults to Text.
+ * @param {Function} [props.onPressEvent] (event, dateKey) => void
+ * @param {boolean} [props.shadow] Passed through to every Panel.
+ * @param {object} [props.containerStyle]
+ * @param {object} [props.dayHeadingStyle]
+ * @param {object} [props.eventTitleStyle]
+ * @param {object} [props.eventDescriptionStyle]
+ *
+ * @returns {JSX.Element}
+ */
+export default function Schedule({
+  schedule,
+  washColors = [],
+  formatDate = (dateKey) => dateKey,
+  TextComponent = Text,
+  onPressEvent,
+  shadow,
+  containerStyle,
+  dayHeadingStyle,
+  eventTitleStyle,
+  eventDescriptionStyle,
+}) {
+  const days = Object.keys(schedule || {});
+
+  return (
+    <View style={[defaultStyle.container, containerStyle]}>
+      {days.map((dateKey, dayIndex) => {
+        const events = schedule[dateKey] || [];
+        const backgroundColor = washColors.length
+          ? washColors[dayIndex % washColors.length]
+          : undefined;
+
+        return (
+          <Panel key={dateKey} backgroundColor={backgroundColor} shadow={shadow}>
+            <TextComponent style={[defaultStyle.dayHeading, dayHeadingStyle]}>
+              {formatDate(dateKey)}
+            </TextComponent>
+
+            {events.map((item, eventIndex) => (
+              <View key={eventIndex} style={defaultStyle.event}>
+                <TextComponent
+                  style={[defaultStyle.eventTitle, eventTitleStyle]}
+                  onPress={onPressEvent ? () => onPressEvent(item, dateKey) : undefined}
+                >
+                  {item.event}
+                </TextComponent>
+
+                {item.description ? (
+                  <TextComponent style={eventDescriptionStyle}>
+                    {item.description}
+                  </TextComponent>
+                ) : null}
+              </View>
+            ))}
+          </Panel>
+        );
+      })}
+    </View>
+  );
+}

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-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.16";
 
 // TODO: @opndev/util?
 export { formatPrice } from './utils/format-price.js';

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

@@ -0,0 +1,189 @@
+// 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';
+
+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;
+
+  return (
+    <View
+      style={[
+        defaultStyle.container,
+        containerStyle,
+      ]}
+    >
+      {showTitleRow ? (
+        <View
+          style={[
+            defaultStyle.titleRow,
+            { justifyContent: title ? 'space-between' : 'flex-end' },
+          ]}
+        >
+          {title ? (
+            <TextComponent style={[defaultStyle.title, 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, itemTextStyle]}>{'\u2022'}</TextComponent>
+          ) : null}
+          <View style={defaultStyle.itemBody}>
+            <TextComponent style={itemTextStyle}>
+              {item.title}
+            </TextComponent>
+            {item.description ? (
+              <TextComponent style={descriptionStyle}>
+                {item.description}
+              </TextComponent>
+            ) : null}
+          </View>
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+

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

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import {
+  forwardRef,
+  useImperativeHandle,
+} from 'react';
+
+import { useJsonApiData } from '../hooks/use-json-api-data';
+import DataListWidget from './data-list-widget';
+
+/**
+ * RemoteDataWidget
+ *
+ * Fetches from a remote JSON endpoint via useJsonApiData, then hands
+ * the result to DataListWidget for rendering. This component owns no
+ * rendering of its own — it's the "where the data comes from" half
+ * of the pair, mirrored by StaticDataWidget for data you already
+ * have. `mapItem` is the contract: whatever shape your API actually
+ * returns, map it to `{ id, title, description? }` and neither this
+ * component nor DataListWidget needs to know anything else about it.
+ *
+ * Includes a small refresh button next to the title, rate-limited
+ * via useJsonApiData's manual-refresh cooldown (regularMs/
+ * manualLockMs/errorRefreshMs — see useJsonApiData for details).
+ * Set showRefreshButton={false} to omit it entirely.
+ *
+ * App-specific presets (e.g. a NewsWidget that always points at
+ * your news endpoint with your styling) are expected to be built on
+ * top of this in your own app code.
+ *
+ * @param {object} props
+ * @param {string} props.uri
+ * @param {string} [props.bearerToken]
+ * @param {string} [props.jpath] Dot-path to the array within the response. Omit if the response IS the array.
+ * @param {(rawItem: any) => { id: any, title: string, description?: string }} [props.mapItem] Defaults to identity.
+ * @param {Function} [props.fetcher] Override for custom auth/caching. See useJsonApiData.
+ * @param {number} [props.refreshIntervalMs] Defaults to 15 minutes. Pass 0 to disable polling.
+ * @param {number} [props.regularMs] Data freshness window. Defaults to 15 minutes.
+ * @param {number} [props.manualLockMs] Manual refresh button cooldown after success. Defaults to 15 minutes.
+ * @param {number} [props.errorRefreshMs] Manual refresh button cooldown after a failed attempt. Defaults to 5 minutes.
+ * ...plus all of DataListWidget's display props (title, dividerStyle, showRefreshButton, TextComponent, onPressItem, styles, etc.)
+ *
+ * @returns {JSX.Element}
+ */
+const RemoteDataWidget = forwardRef(function RemoteDataWidget(
+  {
+    uri,
+    bearerToken,
+    jpath,
+    mapItem,
+    fetcher,
+    refreshIntervalMs = 15 * 60 * 1000,
+    regularMs,
+    manualLockMs,
+    errorRefreshMs,
+    ...displayProps
+  },
+  ref
+) {
+  const { items, loading, error, refresh, manualRefresh, canManualRefresh } = useJsonApiData({
+    uri,
+    bearerToken,
+    jpath,
+    mapItem,
+    fetcher,
+    refreshIntervalMs,
+    regularMs,
+    manualLockMs,
+    errorRefreshMs,
+  });
+
+  useImperativeHandle(ref, () => ({ refresh }), [refresh]);
+
+  return (
+    <DataListWidget
+      items={items}
+      loading={loading}
+      error={error}
+      manualRefresh={manualRefresh}
+      canManualRefresh={canManualRefresh}
+      {...displayProps}
+    />
+  );
+});
+
+export default RemoteDataWidget;

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

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { useStaticData } from '../hooks/use-static-data';
+import DataListWidget from './data-list-widget';
+
+/**
+ * StaticDataWidget
+ *
+ * Renders data you already have via useStaticData, then hands the
+ * result to DataListWidget — the exact same rendering RemoteDataWidget
+ * uses. The two components are identical except for where `items`
+ * comes from: RemoteDataWidget digs through an API response (jpath,
+ * polling, caching); this one just reshapes whatever `data` you pass
+ * in. `mapItem` is the same contract either way — map your raw items
+ * to `{ id, title, description? }`.
+ *
+ * showRefreshButton AND showBullet both default to false here
+ * (unlike RemoteDataWidget, where both default to true) — there's
+ * nothing to refresh against static data, and events generally read
+ * cleaner flush-left than bulleted. Pass either explicitly if you
+ * want them anyway.
+ *
+ * @param {object} props
+ * @param {any[]} props.data
+ * @param {(rawItem: any) => { id: any, title: string, description?: string }} [props.mapItem] Defaults to identity.
+ * ...plus all of DataListWidget's display props (title, dividerStyle, TextComponent, onPressItem, styles, etc.)
+ *
+ * @returns {JSX.Element}
+ */
+export default function StaticDataWidget({ data, mapItem, ...displayProps }) {
+  const { items, loading, error, manualRefresh, canManualRefresh } = useStaticData({
+    data,
+    mapItem,
+  });
+
+  return (
+    <DataListWidget
+      items={items}
+      loading={loading}
+      error={error}
+      manualRefresh={manualRefresh}
+      canManualRefresh={canManualRefresh}
+      showRefreshButton={false}
+      showBullet={false}
+      {...displayProps}
+    />
+  );
+}

package/lib/widgets.js

@@ -2,4 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 
-export { default as NewsWidget } from './widgets/news-widget.jsx';
+export { default as RemoteDataWidget } from './widgets/remote-data-widget';
+export { default as StaticDataWidget } from './widgets/static-data-widget';
+export { default as DataListWidget } from './widgets/data-list-widget';
+export { useJsonApiData, fetchJson, clearJsonCache } from './hooks/use-json-api-data';
+export { useStaticData } from './hooks/use-static-data';

package/package.json

@@ -35,5 +35,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.15"
+  "version": "0.0.16"
 }

package/lib/widgets/news-widget.jsx

@@ -1,190 +0,0 @@
-// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
-//
-// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
-
-import React, {
-  forwardRef,
-  useEffect,
-  useImperativeHandle,
-  useRef,
-  useState,
-} from 'react';
-import {
-  ActivityIndicator,
-  Pressable,
-  StyleSheet,
-  Text,
-  View,
-} from 'react-native';
-
-import { fetchNewsJson } from '../actions/news';
-
-const defaultStyle = StyleSheet.create({
-  container: {
-    gap: 8,
-  },
-  title: {
-    fontWeight: '700',
-  },
-  divider: {
-    height: 1,
-    backgroundColor: 'rgba(0,0,0,0.15)',
-    marginTop: 4,
-    marginBottom: 4,
-  },
-  item: {
-    flexDirection: 'row',
-    gap: 8,
-  },
-  bullet: {
-    opacity: 0.6,
-  },
-  itemText: {
-    flex: 1,
-  },
-});
-
-/**
- * NewsWidget
- *
- * Compact, embeddable "latest N news items" panel — meant to sit
- * inside another page's body (e.g. as one of HeroScreen's children
- * sections), not to own the screen itself. Unlike NewsListScreen,
- * it has no ScrollView and no pull-to-refresh, since both break
- * once nested inside a parent page that's already scrollable.
- *
- * Refreshes itself automatically every `refreshIntervalMs` (default
- * 15 minutes). For anything else that should trigger a refetch —
- * most notably a push notification once that infra exists — attach
- * a ref and call `ref.current.refresh()` from wherever that handler
- * ends up living:
- *
- *   const newsRef = useRef(null);
- *   <NewsWidget ref={newsRef} uri={...} />
- *   // later, e.g. inside a notification handler:
- *   newsRef.current?.refresh();
- *
- * @param {object} props
- * @param {string} props.uri
- * @param {string} [props.bearerToken]
- * @param {number} [props.limit] Max items shown. Defaults to 4.
- * @param {string} [props.title] Defaults to 'News'.
- * @param {boolean} [props.showDivider] Thin line under the title, like 'News' / '-----'. Defaults to true. Ignored if title is falsy.
- * @param {object} [props.dividerStyle]
- * @param {React.ComponentType} [props.TextComponent] Defaults to Text.
- * @param {Function} [props.onPressItem]
- * @param {number} [props.refreshIntervalMs] Defaults to 15 minutes.
- * @param {string} [props.backgroundColor]
- * @param {object} [props.containerStyle]
- * @param {object} [props.titleStyle]
- * @param {object} [props.itemStyle]
- * @param {object} [props.itemTextStyle]
- * @param {object} [props.errorTextStyle]
- * @param {string} [props.emptyLabel]
- * @param {string} [props.errorLabel]
- *
- * @returns {JSX.Element}
- */
-const NewsWidget = forwardRef(function NewsWidget(
-  {
-    uri,
-    bearerToken,
-    limit = 4,
-    title = 'News',
-    showDivider = true,
-    dividerStyle,
-    TextComponent = Text,
-    onPressItem,
-    refreshIntervalMs = 15 * 60 * 1000,
-
-    backgroundColor,
-    containerStyle,
-    titleStyle,
-    itemStyle,
-    itemTextStyle,
-    errorTextStyle,
-
-    emptyLabel = 'No news items.',
-    errorLabel = 'Unable to load news.',
-  },
-  ref
-) {
-  const [items, setItems] = useState([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-  const intervalRef = useRef(null);
-
-  async function load() {
-    setError(null);
-
-    try {
-      const data = await fetchNewsJson({ uri, bearerToken, force: true });
-      setItems((data.items || []).slice(0, limit));
-    }
-    catch (e) {
-      setError(e.message || errorLabel);
-    }
-
-    setLoading(false);
-  }
-
-  useImperativeHandle(ref, () => ({
-    refresh: load,
-  }), [uri, bearerToken, limit]);
-
-  useEffect(() => {
-    setLoading(true);
-    load();
-
-    intervalRef.current = setInterval(load, refreshIntervalMs);
-
-    return () => clearInterval(intervalRef.current);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [uri, bearerToken, limit, refreshIntervalMs]);
-
-  return (
-    <View
-      style={[
-        defaultStyle.container,
-        backgroundColor ? { backgroundColor } : null,
-        containerStyle,
-      ]}
-    >
-      {title ? (
-        <TextComponent style={[defaultStyle.title, titleStyle]}>
-          {title}
-        </TextComponent>
-      ) : null}
-
-      {title && showDivider ? (
-        <View style={[defaultStyle.divider, dividerStyle]} />
-      ) : null}
-
-      {loading ? <ActivityIndicator /> : null}
-
-      {!loading && error ? (
-        <TextComponent style={errorTextStyle}>{error}</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)}
-        >
-          <TextComponent style={defaultStyle.bullet}>{'\u2022'}</TextComponent>
-          <TextComponent style={[defaultStyle.itemText, itemTextStyle]}>
-            {item.title}
-          </TextComponent>
-        </Pressable>
-      ))}
-    </View>
-  );
-});
-
-export default NewsWidget;
-