@opndev/react-native-events 0.0.14 → 0.0.16

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

@@ -11,6 +11,7 @@
   "exports": {
     ".": "./lib/index.js",
     "./components": "./lib/components.js",
+    "./debug": "./lib/debug.js",
     "./globals": "./lib/screen-registry.js",
     "./hero-screen-registry": "./lib/hero-screen-registry.js",
     "./lite": "./lib/hero-screen-registry.js",
@@ -34,5 +35,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.14"
+  "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;
-