@opndev/react-native-events 0.0.15 → 0.0.17

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.17"
 }

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;
-