@opndev/react-native-events 0.0.14 → 0.0.16

package/lib/components/panel.jsx

@@ -6,6 +6,16 @@ import React from 'react';
 import { View, Pressable, StyleSheet } from 'react-native';
 
 const defaultStyle = StyleSheet.create({
+  shadowWrap: {
+    borderRadius: 16,
+  },
+  shadowOn: {
+    elevation: 4,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.15,
+    shadowRadius: 6,
+  },
   surface: {
     borderRadius: 16,
     overflow: 'hidden',
@@ -25,11 +35,20 @@ const defaultStyle = StyleSheet.create({
  * widgets (lists, text blocks, NewsWidget, etc.) render exactly as
  * they would un-wrapped, just inside a rounded/backgrounded card.
  *
+ * Internally split into two layers — an outer view that casts the
+ * shadow (when enabled) and an inner view that clips content to the
+ * rounded corners. This is deliberate: a shadow renders outside a
+ * view's own bounds, so a single view with both `overflow: hidden`
+ * and a shadow would clip its own shadow into invisibility. The
+ * split means `shadow` can be toggled on/off with no other changes
+ * needed, and panels that don't use it are unaffected.
+ *
  * @param {object} props
  * @param {React.ReactNode} props.children
  * @param {string} [props.backgroundColor]
+ * @param {boolean} [props.shadow] Floating-card drop shadow. Defaults to false.
  * @param {Function} [props.onPress] If provided, the whole panel becomes pressable.
- * @param {object} [props.style] Style for the outer rounded surface.
+ * @param {object} [props.style] Style for the outer (shadow-casting) wrapper.
  * @param {object} [props.contentStyle] Style for the inner content wrapper (default padding: 16).
  *
  * @returns {JSX.Element}
@@ -37,6 +56,7 @@ const defaultStyle = StyleSheet.create({
 export default function Panel({
   children,
   backgroundColor,
+  shadow = false,
   onPress,
   style,
   contentStyle,
@@ -44,7 +64,6 @@ export default function Panel({
   const surfaceStyle = [
     defaultStyle.surface,
     backgroundColor ? { backgroundColor } : null,
-    style,
   ];
 
   const content = (
@@ -53,13 +72,28 @@ export default function Panel({
     </View>
   );
 
-  if (onPress) {
-    return (
-      <Pressable onPress={onPress} style={surfaceStyle}>
-        {content}
-      </Pressable>
-    );
-  }
+  const inner = onPress ? (
+    <Pressable onPress={onPress} style={surfaceStyle}>
+      {content}
+    </Pressable>
+  ) : (
+    <View style={surfaceStyle}>{content}</View>
+  );
 
-  return <View style={surfaceStyle}>{content}</View>;
+  return (
+    <View
+      style={[
+        defaultStyle.shadowWrap,
+        shadow ? defaultStyle.shadowOn : null,
+        // Android's elevation shadow needs an opaque shape with a
+        // matching borderRadius to cast a correctly-rounded shadow —
+        // a fully transparent outer view can shadow as a square box
+        // instead of following the rounded silhouette.
+        shadow && backgroundColor ? { backgroundColor } : null,
+        style,
+      ]}
+    >
+      {inner}
+    </View>
+  );
 }

package/lib/components/parallax-scroll-view.js

@@ -11,7 +11,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { useTopOffset, heroContentStyle } from './hero-screen-header';
 
-const DEFAULT_HEADER_HEIGHT = 250;
+const DEFAULT_HEADER_HEIGHT = 220;
 
 const defaultStyle = StyleSheet.create({
   container: {
@@ -50,8 +50,11 @@ const defaultStyle = StyleSheet.create({
  *   Background color for the scroll view container.
  * @param {string} [props.headerBackgroundColor]
  *   Background color shown behind the header image.
- * @param {number} [props.headerHeight=250]
+ * @param {number} [props.headerHeight=220]
  *   Visible height of the parallax header image (excludes the top offset).
+ *   Matches HeroScreenFixed/HeroScreenOverlay's default — kept in
+ *   sync deliberately so all three variants render identically when
+ *   no explicit headerHeight is passed.
  * @param {React.ComponentType<{style?: any, children?: React.ReactNode}>}
  *   [props.ContentComponent=View]
  *   Wrapper used for the content area below the header.

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/debug.js

@@ -0,0 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+export { debugRouteState } from './utils/route-debug.js'

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

package/lib/utils/route-debug.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { useNavigationState } from '@react-navigation/native';
+import { useRouter } from 'expo-router';
+
+export function debugRouteState() {
+  const router = useRouter();
+  const navState = useNavigationState((state) => state);
+
+  console.log('[news stack]',
+    JSON.stringify(navState?.routes?.map((r) => (
+        { name: r.name, params: r.params, key: r.key }
+      )),
+      null,
+      2
+    )
+  );
+
+}