@opndev/react-native-events 0.0.14 → 0.0.16

package/Changes

@@ -1,5 +1,17 @@
 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
+  * Throw shade at panels: I mean shadows, we not dissing panels here.
+
 0.0.14       2026-06-26 04:53:23Z
 
   * Add Panel instead of a Tile, Tiles are more buttony thing. Panels are

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/app-screen-top-bar.jsx

@@ -84,10 +84,10 @@ export default function AppScreenTopBar({
   return (
     <View
       style={[
+        style,
         styles.bar,
         { height, justifyContent, paddingHorizontal: horizontalPadding, paddingBottom: verticalPadding },
         backgroundColor ? { backgroundColor } : null,
-        style,
       ]}
     >
       {applyBarStyling(logo, { height, maxWidthPixels })}

package/lib/components/app-screen.jsx

@@ -1,7 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
-
 import { View, StyleSheet } from 'react-native';
 import { useSafeAreaTopInset } from '../hooks/use-safe-area-top-inset';
 import { AppScreenOffsetContext } from '../hooks/use-app-screen-offset';
@@ -17,6 +16,7 @@ const defaultStyle = StyleSheet.create({
     left: 0,
     width: '100%',
     zIndex: 10,
+    elevation: 10,
   },
 });
 
@@ -67,6 +67,7 @@ export default function AppScreen({
             style={[
               defaultStyle.topBarWrap,
               { height: offset, paddingTop: insetTop },
+              topBar.props?.backgroundColor ? { backgroundColor: topBar.props.backgroundColor } : null,
             ]}
           >
             {topBar}

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

@@ -4,8 +4,9 @@
 
 import { View, ScrollView, StyleSheet } from 'react-native';
 import {
-  renderHeaderImage,
   HeaderOverlay,
+  HeaderContent,
+  splitCarouselChildren,
   useHeroHeaderHeight,
   heroContentStyle,
 } from './hero-screen-header';
@@ -38,9 +39,12 @@ const defaultStyle = StyleSheet.create({
  * gap: 16 — so spacing matches the parallax variant exactly.
  *
  * @param {object} props
- * @param {React.ReactNode} props.children
- * @param {object} [props.headerImage]
+ * @param {React.ReactNode} props.children Normal body content, and/or <CarouselScreen> elements for slides.
+ * @param {object} [props.headerImage] Used when there are no <CarouselScreen> children.
  * @param {React.ReactNode} [props.headerOverlay]
+ * @param {(slide: { item: any, route: any }, index: number) => void} [props.onSlidePress]
+ * @param {number} [props.autoPlayInterval] Defaults to 4000. Pass 0 to disable.
+ * @param {boolean} [props.loop] Defaults to true.
  * @param {string} [props.backgroundColor]
  * @param {string} [props.headerBackgroundColor]
  * @param {number} [props.headerHeight] Visible image height (excludes the safe-area inset)
@@ -55,6 +59,9 @@ export default function HeroScreenFixed({
   children,
   headerImage,
   headerOverlay,
+  onSlidePress,
+  autoPlayInterval,
+  loop,
   backgroundColor,
   headerBackgroundColor,
   headerHeight = 220,
@@ -63,7 +70,8 @@ export default function HeroScreenFixed({
   headerStyle,
   contentStyle,
 }) {
-  const { insetTop, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
+  const { topOffset, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
+  const { slideElements, bodyChildren } = splitCarouselChildren(children);
 
   return (
     <View
@@ -84,10 +92,16 @@ export default function HeroScreenFixed({
         <View
           style={[
             defaultStyle.imageInner,
-            { top: insetTop, height: headerHeight },
+            { top: topOffset, height: headerHeight },
           ]}
         >
-          {renderHeaderImage(headerImage)}
+          <HeaderContent
+            headerImage={headerImage}
+            slideElements={slideElements}
+            onSlidePress={onSlidePress}
+            autoPlayInterval={autoPlayInterval}
+            loop={loop}
+          />
         </View>
       </View>
 
@@ -97,7 +111,7 @@ export default function HeroScreenFixed({
       >
         <View style={[heroContentStyle, contentStyle]}>
           <HeaderOverlay headerOverlay={headerOverlay} />
-          {children}
+          {bodyChildren}
         </View>
       </ContentComponent>
     </View>

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

@@ -2,8 +2,10 @@
 //
 // 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';
+import Carousel from 'react-native-reanimated-carousel';
 import { useAppScreenOffset } from '../hooks/use-app-screen-offset';
 
 const styles = StyleSheet.create({
@@ -25,6 +27,27 @@ const styles = StyleSheet.create({
     shadowOpacity: 0.3,
     shadowRadius: 3,
   },
+  carouselFill: StyleSheet.absoluteFillObject,
+  slideFill: { flex: 1 },
+  dotsRow: {
+    position: 'absolute',
+    bottom: 12,
+    left: 0,
+    right: 0,
+    flexDirection: 'row',
+    justifyContent: 'center',
+    gap: 6,
+  },
+  dot: {
+    width: 6,
+    height: 6,
+    borderRadius: 3,
+    backgroundColor: 'rgba(255,255,255,0.5)',
+  },
+  dotActive: {
+    backgroundColor: '#FFFFFF',
+    width: 16,
+  },
 });
 
 /**
@@ -66,6 +89,140 @@ export function HeaderOverlay({ headerOverlay }) {
   return <View style={styles.titleWrap}>{headerOverlay}</View>;
 }
 
+/**
+ * CarouselScreen
+ *
+ * A marker component, not a real standalone screen — used as a
+ * child of any Hero variant to declare one carousel slide:
+ *
+ *   <HeroScreenFixed onSlidePress={(slide) => router.push(slide.route)}>
+ *     <CarouselScreen item={fooData} route="/foo">
+ *       ...whatever JSX you want for this slide...
+ *     </CarouselScreen>
+ *     <CarouselScreen item={barData} route="/bar">
+ *       ...
+ *     </CarouselScreen>
+ *   </HeroScreenFixed>
+ *
+ * Every Hero variant scans its children for these by type (via
+ * splitCarouselChildren below) and pulls out `item`/`route` plus
+ * your own nested children for each slide. Any non-CarouselScreen
+ * children are treated as normal body content, same as always.
+ *
+ * If rendered standalone it just renders its own children, so it's
+ * harmless either way.
+ *
+ * @param {object} props
+ * @param {any} [props.item]
+ * @param {any} [props.route]
+ * @param {React.ReactNode} props.children
+ */
+export function CarouselScreen({ children }) {
+  return children ?? null;
+}
+
+/**
+ * splitCarouselChildren
+ *
+ * Separates a Hero variant's children into carousel slides
+ * (CarouselScreen elements) and normal body content (everything
+ * else). Shared by every Hero variant so the splitting logic is
+ * identical across all of them.
+ *
+ * @param {React.ReactNode} children
+ * @returns {{ slideElements: React.ReactElement[], bodyChildren: React.ReactNode[] }}
+ */
+export function splitCarouselChildren(children) {
+  const childArray = Children.toArray(children);
+
+  const slideElements = childArray.filter(
+    (child) => isValidElement(child) && child.type === CarouselScreen
+  );
+  const bodyChildren = childArray.filter(
+    (child) => !(isValidElement(child) && child.type === CarouselScreen)
+  );
+
+  return { slideElements, bodyChildren };
+}
+
+/**
+ * HeaderContent
+ *
+ * The single thing every Hero variant renders inside its header
+ * box — decides whether that's a static image (renderHeaderImage,
+ * unchanged default behaviour) or a swipeable/auto-advancing
+ * carousel (when CarouselScreen children were found), so a Hero
+ * variant only ever needs to swap one line to gain carousel
+ * support, with zero changes to its own scroll/positioning logic.
+ *
+ * Fills whatever box it's placed in — each variant owns its own
+ * positioning (Fixed/Overlay via their own imageInner wrapper,
+ * Parallax via ParallaxScrollView's existing wrapper) — this
+ * component doesn't position itself.
+ *
+ * @param {object} props
+ * @param {object} [props.headerImage] Used when there are no slides.
+ * @param {React.ReactElement[]} [props.slideElements] From splitCarouselChildren. When empty/absent, renders the static image instead.
+ * @param {(slide: { item: any, route: any }, index: number) => void} [props.onSlidePress]
+ * @param {number} [props.autoPlayInterval] Defaults to 4000. Pass 0 to disable.
+ * @param {boolean} [props.loop] Defaults to true.
+ *
+ * @returns {JSX.Element|null}
+ */
+export function HeaderContent({
+  headerImage,
+  slideElements,
+  onSlidePress,
+  autoPlayInterval = 4000,
+  loop = true,
+}) {
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  if (!slideElements || slideElements.length === 0) {
+    return renderHeaderImage(headerImage);
+  }
+
+  return (
+    <View style={styles.carouselFill}>
+      <Carousel
+        style={{ width: '100%', height: '100%' }}
+        data={slideElements}
+        loop={loop}
+        autoPlay={autoPlayInterval > 0}
+        autoPlayInterval={autoPlayInterval}
+        onSnapToItem={setActiveIndex}
+        renderItem={({ item: slideElement, index }) => {
+          const { item, route } = slideElement.props;
+          const onPress = onSlidePress
+            ? () => onSlidePress({ item, route }, index)
+            : undefined;
+
+          if (!onPress) {
+            return <View style={styles.slideFill}>{slideElement}</View>;
+          }
+
+          return (
+            <Pressable style={styles.slideFill} onPress={onPress}>
+              {slideElement}
+            </Pressable>
+          );
+        }}
+      />
+
+      {slideElements.length > 1 ? (
+        <View style={styles.dotsRow}>
+          {slideElements.map((_, i) => (
+            <View
+              key={i}
+              style={[styles.dot, i === activeIndex ? styles.dotActive : null]}
+            />
+          ))}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
 /**
  * useTopOffset
  *

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

@@ -2,49 +2,78 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 
-import { View, StyleSheet } from 'react-native';
+import {
+  HeaderOverlay,
+  HeaderContent,
+  splitCarouselChildren,
+} from './hero-screen-header';
 import ParallaxScrollView from './parallax-scroll-view';
-import { renderHeaderImage, HeaderOverlay } from './hero-screen-header';
 
-const defaultStyle = StyleSheet.create({
-  headerImageWrap: {
-    width: '100%',
-    height: 220,
-    bottom: 0,
-    left: 0,
-    position: 'absolute',
-  },
-});
-
-export default function HeroScreen({
+/**
+ * HeroScreenParallax
+ *
+ * Header image scales/translates with scroll (the classic parallax
+ * effect) via ParallaxScrollView. Carousel support needed no new
+ * positioning logic here at all — ParallaxScrollView already treats
+ * its header as an opaque element it animates, so swapping in
+ * HeaderContent (image-or-carousel) instead of a plain image just
+ * works, same one-line swap as Fixed/Overlay.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children Normal body content, and/or <CarouselScreen> elements for slides.
+ * @param {object} [props.headerImage] Used when there are no <CarouselScreen> children.
+ * @param {React.ReactNode} [props.headerOverlay]
+ * @param {(slide: { item: any, route: any }, index: number) => void} [props.onSlidePress]
+ * @param {number} [props.autoPlayInterval] Defaults to 4000. Pass 0 to disable.
+ * @param {boolean} [props.loop] Defaults to true.
+ * @param {string} [props.backgroundColor]
+ * @param {string} [props.headerBackgroundColor]
+ * @param {number} [props.headerHeight] Visible image height (excludes the safe-area inset)
+ * @param {React.ComponentType} [props.ContentComponent]
+ * @param {object} [props.containerStyle]
+ * @param {object} [props.headerStyle]
+ * @param {object} [props.contentStyle]
+ *
+ * @returns {JSX.Element}
+ */
+export default function HeroScreenParallax({
   children,
   headerImage,
   headerOverlay,
+  onSlidePress,
+  autoPlayInterval,
+  loop,
   backgroundColor,
   headerBackgroundColor,
   headerHeight,
-  ContentComponent,
   containerStyle,
   headerStyle,
   contentStyle,
+  ContentComponent,
 }) {
+  const { slideElements, bodyChildren } = splitCarouselChildren(children);
+
   return (
     <ParallaxScrollView
+      headerImage={
+        <HeaderContent
+          headerImage={headerImage}
+          slideElements={slideElements}
+          onSlidePress={onSlidePress}
+          autoPlayInterval={autoPlayInterval}
+          loop={loop}
+        />
+      }
       backgroundColor={backgroundColor}
       headerBackgroundColor={headerBackgroundColor}
       headerHeight={headerHeight}
-      ContentComponent={ContentComponent}
       containerStyle={containerStyle}
       headerStyle={headerStyle}
       contentStyle={contentStyle}
-      headerImage={
-        <View style={defaultStyle.headerImageWrap}>
-          {renderHeaderImage(headerImage)}
-        </View>
-      }
+      ContentComponent={ContentComponent}
     >
       <HeaderOverlay headerOverlay={headerOverlay} />
-      {children}
+      {bodyChildren}
     </ParallaxScrollView>
   );
 }

package/lib/components/hero-screen.jsx

@@ -4,8 +4,9 @@
 
 import { View, ScrollView, StyleSheet } from 'react-native';
 import {
-  renderHeaderImage,
   HeaderOverlay,
+  HeaderContent,
+  splitCarouselChildren,
   BackButton,
   useHeroHeaderHeight,
   heroContentStyle,
@@ -44,10 +45,13 @@ const defaultStyle = StyleSheet.create({
  * own padded content area.
  *
  * @param {object} props
- * @param {React.ReactNode} props.children
- * @param {object} [props.headerImage]
+ * @param {React.ReactNode} props.children Normal body content, and/or <CarouselScreen> elements for slides.
+ * @param {object} [props.headerImage] Used when there are no <CarouselScreen> children.
  * @param {React.ReactNode} [props.headerOverlay]
- * @param {Function} [props.onBack] Renders a back button over the header image when provided. Omit for no back button.
+ * @param {Function} [props.onBack] Renders a back button over the header when provided. Omit for no back button.
+ * @param {(slide: { item: any, route: any }, index: number) => void} [props.onSlidePress]
+ * @param {number} [props.autoPlayInterval] Defaults to 4000. Pass 0 to disable.
+ * @param {boolean} [props.loop] Defaults to true.
  * @param {string} [props.backgroundColor]
  * @param {string} [props.headerBackgroundColor]
  * @param {number} [props.headerHeight] Visible image height (excludes the safe-area inset)
@@ -63,6 +67,9 @@ export default function HeroScreenOverlay({
   headerImage,
   headerOverlay,
   onBack,
+  onSlidePress,
+  autoPlayInterval,
+  loop,
   backgroundColor,
   headerBackgroundColor,
   headerHeight = 220,
@@ -72,6 +79,7 @@ export default function HeroScreenOverlay({
   contentStyle,
 }) {
   const { topOffset, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
+  const { slideElements, bodyChildren } = splitCarouselChildren(children);
 
   return (
     <View
@@ -89,7 +97,7 @@ export default function HeroScreenOverlay({
 
         <View style={[heroContentStyle, contentStyle]}>
           <HeaderOverlay headerOverlay={headerOverlay} />
-          {children}
+          {bodyChildren}
         </View>
       </ContentComponent>
 
@@ -107,7 +115,13 @@ export default function HeroScreenOverlay({
             { top: topOffset, height: headerHeight },
           ]}
         >
-          {renderHeaderImage(headerImage)}
+          <HeaderContent
+            headerImage={headerImage}
+            slideElements={slideElements}
+            onSlidePress={onSlidePress}
+            autoPlayInterval={autoPlayInterval}
+            loop={loop}
+          />
         </View>
 
         <BackButton