@opndev/react-native-events 0.0.11 → 0.0.13

package/Changes

@@ -1,5 +1,16 @@
 Revision history for @opndev/opndev-react-native-events
 
+0.0.13       2026-06-26 03:59:55Z
+
+  * Update news item segment to be included as a widget.
+    This infra is highly sus for generic dynamic pages infra. I need some more
+    hours in a day to get perhaps get that to work nicely. but getting there.
+
+0.0.12       2026-06-25 23:24:45Z
+
+  * Add top bar to package
+  * Add more HeroScreen types
+
 0.0.11       2026-06-25 04:12:51Z
 
   * registry not registery :/

package/lib/actions/qrcode.js

@@ -66,9 +66,6 @@ export default class QRCodeAction {
       ? this.buildPayload(values)
       : values;
 
-    console.log(this.endpoint);
-    console.log(payload);
-
     const res = await fetch(this.endpoint.url, {
       method: this.endpoint.method || 'POST',
       headers: {

package/lib/components/app-screen-top-bar.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 { cloneElement, isValidElement } from 'react';
+import { View, StyleSheet, useWindowDimensions } from 'react-native';
+
+export const DEFAULT_TOP_BAR_HEIGHT = 56;
+export const DEFAULT_MAX_WIDTH_PERCENT = 33;
+
+const styles = StyleSheet.create({
+  bar: {
+    flexDirection: 'row',
+    alignItems: 'flex-end',
+    width: '100%',
+  },
+});
+
+/**
+ * Injects the bar's own height (unless the caller already set an
+ * explicit height or width) and a pixel maxWidth clamp into a logo
+ * element (e.g. ScaledLogo). The clamp is passed as a `maxWidth`
+ * PROP, not a style percentage — ScaledLogo re-derives height from
+ * the clamped width itself, so nothing ever letterboxes.
+ */
+function applyBarStyling(element, { height, maxWidthPixels }) {
+  if (!isValidElement(element)) return element;
+
+  const props = {};
+
+  if (element.props.height == null && element.props.width == null) {
+    props.height = height;
+  }
+
+  if (maxWidthPixels != null && element.props.maxWidth == null) {
+    props.maxWidth = maxWidthPixels;
+  }
+
+  return cloneElement(element, props);
+}
+
+/**
+ * AppScreenTopBar
+ *
+ * Purely presentational — the logo / sponsor-logo row. It knows
+ * nothing about safe areas, positioning, or stacking order; all of
+ * that is owned by AppScreen, which renders this as its `topBar`.
+ *
+ * `logo` / `sponsorLogo` automatically receive a `height` matching
+ * the bar's own height, and a pixel `maxWidth` clamp (default 33%
+ * of the screen width) that ScaledLogo applies aspect-ratio-aware —
+ * so nothing to keep in sync manually, and no letterboxing if a
+ * logo would otherwise render too wide on a narrow screen. Pass an
+ * explicit `height` or `width` on the logo element yourself to opt
+ * out of the auto-sizing.
+ *
+ * With no `sponsorLogo`, `logo` is centered rather than left-aligned
+ * — there's nothing to space it apart from.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} [props.logo]
+ * @param {React.ReactNode} [props.sponsorLogo]
+ * @param {number} [props.height] Defaults to DEFAULT_TOP_BAR_HEIGHT (56). If you override this, pass the same value to AppScreen's `topBarHeight` so the reserved offset still matches.
+ * @param {number} [props.maxWidthPercent] Defaults to 33 (% of screen width). Pass null to disable the clamp entirely.
+ * @param {number} [props.horizontalPadding] Space from the screen edges. Defaults to 24.
+ * @param {string} [props.backgroundColor]
+ * @param {object} [props.style]
+ *
+ * @returns {JSX.Element}
+ */
+export default function AppScreenTopBar({
+  logo,
+  sponsorLogo,
+  height = DEFAULT_TOP_BAR_HEIGHT,
+  maxWidthPercent = DEFAULT_MAX_WIDTH_PERCENT,
+  horizontalPadding = 24,
+  verticalPadding = 8,
+  backgroundColor,
+  style,
+}) {
+  const { width: windowWidth } = useWindowDimensions();
+  const maxWidthPixels = maxWidthPercent != null ? (windowWidth * maxWidthPercent) / 100 : null;
+  const justifyContent = sponsorLogo ? 'space-between' : 'center';
+
+  return (
+    <View
+      style={[
+        styles.bar,
+        { height, justifyContent, paddingHorizontal: horizontalPadding, paddingBottom: verticalPadding },
+        backgroundColor ? { backgroundColor } : null,
+        style,
+      ]}
+    >
+      {applyBarStyling(logo, { height, maxWidthPixels })}
+      {sponsorLogo ? applyBarStyling(sponsorLogo, { height, maxWidthPixels }) : null}
+    </View>
+  );
+}

package/lib/components/app-screen.jsx

@@ -0,0 +1,78 @@
+// 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';
+import { DEFAULT_TOP_BAR_HEIGHT } from './app-screen-top-bar';
+
+const defaultStyle = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  topBarWrap: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: '100%',
+    zIndex: 10,
+  },
+});
+
+/**
+ * AppScreen
+ *
+ * The mandatory root wrapper for every screen in the app. Owns
+ * safe-area handling as a baseline — wrap every screen in this,
+ * even ones with no visible top bar. Optionally floats a `topBar`
+ * (e.g. AppScreenTopBar) above everything, and publishes the
+ * combined offset via AppScreenOffsetContext so any nested screen
+ * (HeroScreen, HeroScreenParallax, HeroScreenFixed,
+ * HeroScreenOverlay, Screen) automatically starts its own
+ * content/header below it — no per-screen wiring needed.
+ *
+ * In practice, you only need ONE AppScreen, at the root of your
+ * navigator (e.g. wrapping <Slot/> in app/_layout.tsx), rather
+ * than wrapping every individual screen file — context propagates
+ * to the whole tree underneath it.
+ *
+ * Screens rendered WITHOUT an AppScreen ancestor get an offset of
+ * 0 (no safe-area protection) — that's intentional now that
+ * AppScreen is the single owner of this concern, not a fallback
+ * gap. Make sure the root wrap is always in place.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children The screen tree (HeroScreen*, Screen, a navigator, etc.)
+ * @param {React.ReactNode} [props.topBar] e.g. <AppScreenTopBar .../>. Omit for no branding bar.
+ * @param {number} [props.topBarHeight] Visible height of `topBar`. Defaults to AppScreenTopBar's own default height (56) — only override if you also customized AppScreenTopBar's height.
+ *
+ * @returns {JSX.Element}
+ */
+export default function AppScreen({
+  children,
+  topBar,
+  topBarHeight = DEFAULT_TOP_BAR_HEIGHT,
+}) {
+  const insetTop = useSafeAreaTopInset();
+  const offset = topBar ? insetTop + topBarHeight : insetTop;
+
+  return (
+    <AppScreenOffsetContext.Provider value={offset}>
+      <View style={defaultStyle.container}>
+        {children}
+
+        {topBar ? (
+          <View
+            style={[
+              defaultStyle.topBarWrap,
+              { height: offset, paddingTop: insetTop },
+            ]}
+          >
+            {topBar}
+          </View>
+        ) : null}
+      </View>
+    </AppScreenOffsetContext.Provider>
+  );
+}

package/lib/components/base-screen.jsx

@@ -1,10 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
 import { View, ScrollView, StyleSheet } from 'react-native';
-import { useSafeAreaTopInset } from '../hooks/use-safe-area-top-inset.js';
+import { useTopOffset } from './hero-screen-header';
 
 const defaultStyle = StyleSheet.create({
   container: {
     flex: 1,
   },
+  content: {
+    flex: 1,
+  },
 });
 
 /**
@@ -13,9 +20,9 @@ const defaultStyle = StyleSheet.create({
  * Plain screen wrapper for content that doesn't have a hero header
  * image (e.g. NewsListScreen, FoodMenuScreen). Encapsulates the
  * same background / safe-area / scroll-container concerns as the
- * HeroScreen variants, minus the header, so non-hero screens still
- * get consistent top-inset behaviour rather than each handling it
- * (or forgetting to handle it) separately.
+ * HeroScreen variants, minus the header. Automatically starts
+ * content below an enclosing AppScreen's bar when present (via
+ * useTopOffset), same as the Hero variants do.
  *
  * @param {object} props
  * @param {React.ReactNode} props.children
@@ -23,7 +30,7 @@ const defaultStyle = StyleSheet.create({
  * @param {React.ComponentType} [props.ContentComponent] Defaults to ScrollView; pass a list component (FlatList/SectionList) if children render as list items
  * @param {object} [props.containerStyle]
  * @param {object} [props.contentStyle]
- * @param {boolean} [props.useSafeArea] Pad content by the top safe-area inset. Defaults true.
+ * @param {boolean} [props.useSafeArea] Pad content by the top offset (safe-area inset, or AppScreen bar height if present). Defaults true.
  *
  * @returns {JSX.Element}
  */
@@ -35,7 +42,7 @@ export default function BaseScreen({
   contentStyle,
   useSafeArea = true,
 }) {
-  const insetTop = useSafeAreaTopInset();
+  const topOffset = useTopOffset();
 
   return (
     <View
@@ -46,8 +53,8 @@ export default function BaseScreen({
       ]}
     >
       <ContentComponent
-        style={[contentStyle]}
-        contentContainerStyle={useSafeArea ? { paddingTop: insetTop } : null}
+        style={[defaultStyle.content, contentStyle]}
+        contentContainerStyle={useSafeArea ? { paddingTop: topOffset } : null}
       >
         {children}
       </ContentComponent>

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

@@ -1,8 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
 import { View, ScrollView, StyleSheet } from 'react-native';
 import {
   renderHeaderImage,
   HeaderOverlay,
-  useHeroHeaderHeight
+  useHeroHeaderHeight,
+  heroContentStyle,
 } from './hero-screen-header';
 
 const defaultStyle = StyleSheet.create({
@@ -28,7 +33,9 @@ const defaultStyle = StyleSheet.create({
  * Header image stays pinned in place; only the content below it
  * scrolls. The image never overlaps the status bar — a solid
  * headerBackgroundColor strip (sized to the safe-area top inset,
- * via useHeroHeaderHeight) sits above it.
+ * via useHeroHeaderHeight) sits above it. Body content is wrapped
+ * the same way ParallaxScrollView wraps its children — padding: 32,
+ * gap: 16 — so spacing matches the parallax variant exactly.
  *
  * @param {object} props
  * @param {React.ReactNode} props.children
@@ -85,11 +92,13 @@ export default function HeroScreenFixed({
       </View>
 
       <ContentComponent
-        style={[contentStyle]}
+        style={{ flex: 1 }}
         contentContainerStyle={{ paddingTop: totalHeaderHeight }}
       >
-        <HeaderOverlay headerOverlay={headerOverlay} />
-        {children}
+        <View style={[heroContentStyle, contentStyle]}>
+          <HeaderOverlay headerOverlay={headerOverlay} />
+          {children}
+        </View>
       </ContentComponent>
     </View>
   );

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

@@ -1,11 +1,59 @@
-import { View, Image, StyleSheet } from 'react-native';
-import { useSafeAreaTopInset } from '../hooks/use-safe-area-top-inset.js';
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { View, Image, Pressable, StyleSheet } from 'react-native';
+import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
+import { useAppScreenOffset } from '../hooks/use-app-screen-offset';
 
 const styles = StyleSheet.create({
   headerImage: { width: '100%', height: '100%' },
   titleWrap: { paddingHorizontal: 8, paddingTop: 8, paddingBottom: 8 },
+  // Matches ParallaxScrollView's own `content` style — single source of
+  // truth so every Hero variant lines up on body padding/gap.
+  heroContent: { padding: 32, gap: 16 },
+  backButton: {
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    backgroundColor: 'rgba(0,0,0,0.55)',
+    alignItems: 'center',
+    justifyContent: 'center',
+    elevation: 4,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.3,
+    shadowRadius: 3,
+  },
 });
 
+/**
+ * BackButton
+ *
+ * Floating back-chevron button meant to sit over a Hero variant's
+ * header image. Router-agnostic — same pattern as onSlidePress
+ * elsewhere — the package renders the button, the app decides what
+ * tapping it does (typically router.back()).
+ *
+ * Renders nothing if `onBack` isn't provided, so adding this to a
+ * Hero variant is a no-op for screens that don't pass it.
+ *
+ * @param {object} props
+ * @param {Function} [props.onBack]
+ * @param {string} [props.iconColor] Defaults to white.
+ * @param {number} [props.iconSize] Defaults to 22.
+ * @param {object} [props.style] Positioning is the caller's responsibility (e.g. absolute top/left) — this component doesn't position itself.
+ */
+export function BackButton({ onBack, iconColor = '#fff', iconSize = 22, style }) {
+  if (!onBack) return null;
+
+  return (
+    <Pressable onPress={onBack} style={[styles.backButton, style]}>
+      <MaterialCommunityIcons name="arrow-left" size={iconSize} color={iconColor} />
+    </Pressable>
+  );
+}
+
 export function renderHeaderImage(headerImage) {
   if (!headerImage) return null;
   const fit = headerImage.fit || 'cover';
@@ -18,24 +66,42 @@ export function HeaderOverlay({ headerOverlay }) {
   return <View style={styles.titleWrap}>{headerOverlay}</View>;
 }
 
+/**
+ * useTopOffset
+ *
+ * How much vertical space must be reserved at the very top of a
+ * screen before its own content begins. AppScreen is now the sole
+ * owner of this number — it's always the safe-area inset, plus a
+ * top bar's height if AppScreen has one. There's no fallback to a
+ * direct safe-area call here anymore: if a screen has no AppScreen
+ * ancestor, this is 0, by design.
+ *
+ * @returns {number}
+ */
+export function useTopOffset() {
+  return useAppScreenOffset();
+}
+
 /**
  * useHeroHeaderHeight
  *
- * Shared safe-area calculation for all HeroScreen variants, so the
- * "space above the header" behaves identically across Parallax,
- * Fixed, and Overlay rather than each computing it separately.
+ * Shared header-height calculation for every HeroScreen variant
+ * (Parallax, Fixed, Overlay), so the space above the header
+ * behaves identically across all three and automatically starts
+ * below an AppScreen's top bar when present.
  *
- * @param {number} [headerHeight] Visible image height, as passed by the caller (excludes the inset)
- * @returns {{ insetTop: number, headerHeight: number, totalHeaderHeight: number }}
+ * @param {number} [headerHeight] Visible image height, as passed by the caller (excludes the top offset)
+ * @returns {{ topOffset: number, headerHeight: number, totalHeaderHeight: number }}
  */
 export function useHeroHeaderHeight(headerHeight = 220) {
-  const insetTop = useSafeAreaTopInset();
+  const topOffset = useTopOffset();
 
   return {
-    insetTop,
+    topOffset,
     headerHeight,
-    totalHeaderHeight: insetTop + headerHeight,
+    totalHeaderHeight: topOffset + headerHeight,
   };
 }
 
 export { styles as heroImageStyles };
+export const heroContentStyle = styles.heroContent;

package/lib/components/hero-screen-parallax.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 { View, StyleSheet } from 'react-native';
 import ParallaxScrollView from './parallax-scroll-view';
 import { renderHeaderImage, HeaderOverlay } from './hero-screen-header';

package/lib/components/hero-screen.jsx

@@ -6,7 +6,9 @@ import { View, ScrollView, StyleSheet } from 'react-native';
 import {
   renderHeaderImage,
   HeaderOverlay,
-  useHeroHeaderHeight
+  BackButton,
+  useHeroHeaderHeight,
+  heroContentStyle,
 } from './hero-screen-header';
 
 const defaultStyle = StyleSheet.create({
@@ -34,12 +36,18 @@ const defaultStyle = StyleSheet.create({
  * (visible content gets covered by the image as the user scrolls
  * up). The image never overlaps the status bar — a solid
  * headerBackgroundColor strip (sized to the safe-area top inset,
- * via useHeroHeaderHeight) sits above it.
+ * via useHeroHeaderHeight) sits above it. Body content is wrapped
+ * the same way ParallaxScrollView wraps its children — padding: 32,
+ * gap: 16 — so spacing matches the parallax variant exactly. The
+ * spacer that reserves room for the header stays outside that
+ * padded wrapper, same as Parallax keeps its header outside its
+ * own padded content area.
  *
  * @param {object} props
  * @param {React.ReactNode} props.children
  * @param {object} [props.headerImage]
  * @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 {string} [props.backgroundColor]
  * @param {string} [props.headerBackgroundColor]
  * @param {number} [props.headerHeight] Visible image height (excludes the safe-area inset)
@@ -54,6 +62,7 @@ export default function HeroScreenOverlay({
   children,
   headerImage,
   headerOverlay,
+  onBack,
   backgroundColor,
   headerBackgroundColor,
   headerHeight = 220,
@@ -62,7 +71,7 @@ export default function HeroScreenOverlay({
   headerStyle,
   contentStyle,
 }) {
-  const { insetTop, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
+  const { topOffset, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
 
   return (
     <View
@@ -73,12 +82,15 @@ export default function HeroScreenOverlay({
       ]}
     >
       <ContentComponent
-        style={[contentStyle]}
+        style={{ flex: 1 }}
         contentContainerStyle={{ paddingTop: 0 }}
       >
         <View style={{ height: totalHeaderHeight }} />
-        <HeaderOverlay headerOverlay={headerOverlay} />
-        {children}
+
+        <View style={[heroContentStyle, contentStyle]}>
+          <HeaderOverlay headerOverlay={headerOverlay} />
+          {children}
+        </View>
       </ContentComponent>
 
       <View
@@ -92,11 +104,16 @@ export default function HeroScreenOverlay({
         <View
           style={[
             defaultStyle.imageInner,
-            { top: insetTop, height: headerHeight },
+            { top: topOffset, height: headerHeight },
           ]}
         >
           {renderHeaderImage(headerImage)}
         </View>
+
+        <BackButton
+          onBack={onBack}
+          style={{ position: 'absolute', top: topOffset + 12, left: 12 }}
+        />
       </View>
     </View>
   );

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

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { StyleSheet, View } from 'react-native';
+import Animated, {
+  interpolate,
+  useAnimatedRef,
+  useAnimatedStyle,
+  useScrollOffset,
+} from 'react-native-reanimated';
+import { useTopOffset, heroContentStyle } from './hero-screen-header';
+
+const DEFAULT_HEADER_HEIGHT = 250;
+
+const defaultStyle = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  header: {
+    overflow: 'hidden',
+    zIndex: 1,
+  },
+  imageInner: {
+    position: 'absolute',
+    left: 0,
+    width: '100%',
+  },
+});
+
+/**
+ * A scroll view with a parallax header image and a pluggable content wrapper.
+ *
+ * The component is intentionally theme-agnostic. Consumers are expected to pass
+ * resolved colors and, if needed, a custom content wrapper component.
+ *
+ * The header reserves space above the image via useTopOffset() — the
+ * safe-area inset, plus an AppScreen top bar's height if one is
+ * present — so the image itself always renders at exactly
+ * `headerHeight`, with `headerBackgroundColor` as backdrop behind
+ * whatever's reserved above it. Same contract as HeroScreenFixed /
+ * HeroScreenOverlay.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children
+ *   Content rendered below the parallax header.
+ * @param {React.ReactElement} props.headerImage
+ *   Element rendered inside the header area, usually an image.
+ * @param {string} [props.backgroundColor='#fff']
+ *   Background color for the scroll view container.
+ * @param {string} [props.headerBackgroundColor]
+ *   Background color shown behind the header image.
+ * @param {number} [props.headerHeight=250]
+ *   Visible height of the parallax header image (excludes the top offset).
+ * @param {React.ComponentType<{style?: any, children?: React.ReactNode}>}
+ *   [props.ContentComponent=View]
+ *   Wrapper used for the content area below the header.
+ * @param {import('react-native').StyleProp<import('react-native').ViewStyle>}
+ *   [props.containerStyle]
+ *   Optional style overrides for the outer scroll view container.
+ * @param {import('react-native').StyleProp<import('react-native').ViewStyle>}
+ *   [props.headerStyle]
+ *   Optional style overrides for the header container.
+ * @param {import('react-native').StyleProp<import('react-native').ViewStyle>}
+ *   [props.contentStyle]
+ *   Optional style overrides for the content wrapper.
+ * @returns {JSX.Element}
+ */
+export default function ParallaxScrollView({
+  children,
+  headerImage,
+  headerBackgroundColor,
+  backgroundColor = '#fff',
+  colorScheme = 'light',
+  headerHeight = DEFAULT_HEADER_HEIGHT,
+  containerStyle,
+  headerStyle,
+  contentStyle,
+  ContentComponent = View,
+}) {
+  const scrollRef = useAnimatedRef();
+  const scrollOffset = useScrollOffset(scrollRef);
+  const topOffset = useTopOffset();
+  const effectiveHeaderHeight = headerHeight + topOffset;
+
+  const headerAnimatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [
+        {
+          translateY: interpolate(
+            scrollOffset.value,
+            [-headerHeight, 0, headerHeight],
+            [-headerHeight / 2, 0, headerHeight * 0.75]
+          ),
+        },
+        {
+          scale: interpolate(
+            scrollOffset.value,
+            [-headerHeight, 0, headerHeight],
+            [2, 1, 1]
+          ),
+        },
+      ],
+    };
+  });
+
+  return (
+    <Animated.ScrollView
+      ref={scrollRef}
+      style={[
+        defaultStyle.container,
+        { backgroundColor },
+        containerStyle,
+      ]}
+      scrollEventThrottle={16}
+    >
+      <Animated.View
+        style={[
+          defaultStyle.header,
+          {
+            height: effectiveHeaderHeight,
+            backgroundColor: headerBackgroundColor,
+          },
+          headerAnimatedStyle,
+          headerStyle,
+        ]}
+      >
+        <View
+          style={[
+            defaultStyle.imageInner,
+            { top: topOffset, height: headerHeight },
+          ]}
+        >
+          {headerImage}
+        </View>
+      </Animated.View>
+      <ContentComponent style={[heroContentStyle, contentStyle]}>
+        {children}
+      </ContentComponent>
+    </Animated.ScrollView>
+  );
+}

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

@@ -24,8 +24,8 @@ const defaultStyle = StyleSheet.create({
     zIndex: 1,
   },
   content: {
-    padding: 32,
-    gap: 16,
+    padding: 16,
+    gap: 8,
   },
 });
 

package/lib/components/scaled-logo.jsx

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { Image } from 'react-native';
+
+/**
+ * ScaledLogo
+ *
+ * Fits a logo image to a fixed height OR width while preserving its
+ * real aspect ratio — pass whichever dimension you actually care
+ * about, and the other is computed automatically. If both are
+ * given, both are used as-is (no aspect-ratio computation).
+ *
+ * `maxWidth` (in pixels, not a style percentage) is applied AFTER
+ * the natural size is computed, and — critically — height is
+ * re-derived from the clamped width so the box always matches the
+ * aspect ratio. A style-based `maxWidth: '33%'` clamp can't do this:
+ * it shrinks width but leaves height untouched, which (with
+ * resizeMode="contain") leaves the visible artwork letterboxed
+ * inside a too-tall box. Passing `maxWidth` as a prop here avoids
+ * that entirely.
+ *
+ * Deliberately computes explicit width/height rather than relying
+ * on the `aspectRatio` style property — Image has special intrinsic
+ * sizing behaviour that can override `aspectRatio` and fall back to
+ * the image's native pixel size when only one explicit dimension is
+ * given via style. Providing both width and height directly
+ * sidesteps that entirely.
+ *
+ * Works out-of-the-box for local assets (require('...')), since RN
+ * can read their real dimensions synchronously via
+ * Image.resolveAssetSource. For remote ({ uri: ... }) sources, pass
+ * an explicit `aspectRatio` instead — those dimensions aren't known
+ * until the image actually loads.
+ *
+ * @param {object} props
+ * @param {any} props.source Image source (require(...) or { uri }).
+ * @param {number} [props.height] Computed from `width` + aspect ratio if omitted.
+ * @param {number} [props.width] Computed from `height` + aspect ratio if omitted. If neither height nor width is given, defaults to height=32.
+ * @param {number} [props.maxWidth] Pixel clamp applied after natural sizing; height is re-derived from the clamped width, never letterboxed.
+ * @param {number} [props.aspectRatio] Required for remote ({ uri }) sources; ignored for local assets, where it's read automatically.
+ * @param {object} [props.style]
+ *
+ * @returns {JSX.Element}
+ */
+export default function ScaledLogo({ source, height, width, maxWidth, aspectRatio, style }) {
+  let resolvedAspectRatio = aspectRatio;
+
+  if (typeof source === 'number') {
+    // Local asset — RN can resolve real dimensions synchronously.
+    const { width: naturalWidth, height: naturalHeight } = Image.resolveAssetSource(source);
+    resolvedAspectRatio = naturalWidth / naturalHeight;
+  }
+
+  let finalWidth = width;
+  let finalHeight = height;
+
+  if (finalWidth != null && finalHeight == null) {
+    finalHeight = resolvedAspectRatio ? finalWidth / resolvedAspectRatio : undefined;
+  } else if (finalHeight != null && finalWidth == null) {
+    finalWidth = resolvedAspectRatio ? finalHeight * resolvedAspectRatio : undefined;
+  } else if (finalWidth == null && finalHeight == null) {
+    finalHeight = 32;
+    finalWidth = resolvedAspectRatio ? finalHeight * resolvedAspectRatio : undefined;
+  }
+  // If both width and height were explicitly given, use both as-is.
+
+  // Clamp width if needed, then re-derive height so nothing letterboxes.
+  if (maxWidth != null && finalWidth != null && finalWidth > maxWidth) {
+    finalWidth = maxWidth;
+    finalHeight = resolvedAspectRatio ? finalWidth / resolvedAspectRatio : finalHeight;
+  }
+
+  return (
+    <Image
+      source={source}
+      resizeMode="contain"
+      style={[{ height: finalHeight, width: finalWidth }, style]}
+    />
+  );
+}

package/lib/components.js

@@ -10,6 +10,7 @@ export { default as TileBase } from './components/tile-base.jsx';
 export { default as Tile } from './components/tile.jsx';
 export { default as GradientTile } from './components/gradient-tile.jsx';
 export { default as QRCodeForm } from './components/qr-code-form.jsx';
+export { default as ScaledLogo } from './components/scaled-logo.jsx';
 
 export { openUrl, openApp, openExternal } from './utils/launch.js';
 

package/lib/hooks/use-app-screen-offset.js

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { createContext, useContext } from 'react';
+
+/**
+ * AppScreenOffsetContext
+ *
+ * Provided by AppScreen with the total height of its persistent
+ * top bar (safe-area inset + visible bar height). Defaults to 0,
+ * so any screen rendered WITHOUT an AppScreen ancestor behaves
+ * exactly as before — this is additive, not a breaking change.
+ */
+export const AppScreenOffsetContext = createContext(0);
+
+/**
+ * useAppScreenOffset
+ *
+ * @returns {number} Height of the enclosing AppScreen's bar, or 0 if none.
+ */
+export function useAppScreenOffset() {
+  return useContext(AppScreenOffsetContext);
+}

package/lib/hooks/use-safe-area-top-inset.js

@@ -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 { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 /**

package/lib/index.js

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 
-const VERSION = "0.0.11";
+const VERSION = "0.0.13";
 
 // TODO: @opndev/util?
 export { formatPrice } from './utils/format-price.js';

package/lib/screen-registry.js

@@ -4,10 +4,12 @@
 
 import React from 'react';
 
-import BaseScreen from './components/base-screen';
 import HeroScreen from './components/hero-screen';
 import HeroScreenParallax from './components/hero-screen-parallax';
 import HeroScreenFixed from './components/hero-screen-fixed';
+import BaseScreen from './components/base-screen';
+import AppScreen from './components/app-screen';
+import AppScreenTopBar from './components/app-screen-top-bar';
 import Tile from './components/tile';
 
 import FoodMenuScreen from './screens/food-menu-screen';
@@ -65,8 +67,20 @@ export function createScreens({
       <HeroScreenFixed {...props} />
     ),
 
-    BaseScreen: (props) => (
-      <BaseScreen {...props} />
+    HeroScreenOverlay: (props) => (
+      <HeroScreenOverlay {...props} />
+    ),
+
+    Screen: (props) => (
+      <Screen {...props} />
+    ),
+
+    AppScreen: (props) => (
+      <AppScreen {...props} />
+    ),
+
+    AppScreenTopBar: (props) => (
+      <AppScreenTopBar {...props} />
     ),
 
     FoodMenuScreen: (props) => (

package/lib/screens/news-item-screen.jsx

@@ -13,7 +13,6 @@ import {
   View,
 } from 'react-native';
 import Markdown from 'react-native-markdown-display';
-
 import HeroScreen from '../components/hero-screen';
 import { fetchNewsJson } from '../actions/news';
 
@@ -53,18 +52,16 @@ export default function NewsItemScreen({
   TextComponent = Text,
   MarkdownComponent = Markdown,
   defaultHeaderImage,
-
+  onBack,
   backgroundColor,
   headerBackgroundColor,
   headerHeight,
-
   containerStyle,
   headerStyle,
   contentStyle,
   summaryStyle,
   titleStyle,
   markdownStyle,
-
   loadingLabel = 'Loading...',
   errorLabel = 'Unable to load news item.',
 }) {
@@ -100,10 +97,7 @@ export default function NewsItemScreen({
     setLoading(false);
   }
 
-  if (!item) return;
-
   const headerImage = defaultHeaderImage;
-
 //  const headerImage = item?.image
 //    ? {
 //        source: { uri: item.image },
@@ -112,11 +106,47 @@ export default function NewsItemScreen({
 //      }
 //    : defaultHeaderImage;
 
+  // Loading and error states now render through the same HeroScreen
+  // shell (so chrome/background/header stay consistent) instead of
+  // bailing out to a blank screen before item is set.
+  if (loading || error || !item) {
+    return (
+      <HeroScreen
+        TextComponent={TextComponent}
+        titleStyle={titleStyle}
+        headerImage={headerImage}
+        onBack={onBack}
+        backgroundColor={backgroundColor}
+        headerBackgroundColor={headerBackgroundColor}
+        headerHeight={headerHeight}
+        containerStyle={containerStyle}
+        headerStyle={headerStyle}
+        contentStyle={contentStyle}
+      >
+        <View style={defaultStyle.content}>
+          {loading ? (
+            <View>
+              <ActivityIndicator />
+              <TextComponent>{loadingLabel}</TextComponent>
+            </View>
+          ) : null}
+
+          {!loading && error ? (
+            <TextComponent>
+              {error}
+            </TextComponent>
+          ) : null}
+        </View>
+      </HeroScreen>
+    );
+  }
+
   return (
     <HeroScreen
       TextComponent={TextComponent}
       titleStyle={titleStyle}
       headerImage={headerImage}
+        onBack={onBack}
       headerOverlay={
         <TextComponent type="title">
           {item.title}
@@ -130,24 +160,9 @@ export default function NewsItemScreen({
       contentStyle={contentStyle}
     >
       <View style={defaultStyle.content}>
-        {loading ? (
-          <View>
-            <ActivityIndicator />
-            <TextComponent>{loadingLabel}</TextComponent>
-          </View>
-        ) : null}
-
-        {!loading && error ? (
-          <TextComponent>
-            {error}
-          </TextComponent>
-        ) : null}
-
-        {!loading && !error ? (
-          <MarkdownComponent style={markdownStyle}>
-            {item?.content || ''}
-          </MarkdownComponent>
-        ) : null}
+        <MarkdownComponent style={markdownStyle}>
+          {item?.content || ''}
+        </MarkdownComponent>
       </View>
     </HeroScreen>
   );

package/lib/widgets/news-widget.jsx

@@ -0,0 +1,171 @@
+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',
+  },
+  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 {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',
+    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}
+
+      {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;

package/lib/widgets.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 { default as NewsWidget } from './widgets/news-widget.jsx';

package/package.json

@@ -13,12 +13,12 @@
     "./components": "./lib/components.js",
     "./globals": "./lib/screen-registry.js",
     "./hero-screen-registry": "./lib/hero-screen-registry.js",
-    "./hooks/use-safe-area-top-inset": "./lib/hooks/use-safe-area-top-inset.js",
     "./lite": "./lib/hero-screen-registry.js",
     "./notifications": "./lib/notifications.js",
     "./notifications-fcm": "./lib/notifications/fcm.js",
     "./screen-registry": "./lib/screen-registry.js",
-    "./screens": "./lib/screens.js"
+    "./screens": "./lib/screens.js",
+    "./widgets": "./lib/widgets.js"
   },
   "keywords": [],
   "license": "GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions",
@@ -34,5 +34,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.11"
+  "version": "0.0.13"
 }