@opndev/react-native-events 0.0.10 → 0.0.12

package/Changes

@@ -1,5 +1,42 @@
 Revision history for @opndev/opndev-react-native-events
 
+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 :/
+  * Add HeroScreen variants: Parallax, Fixed and Overlay. Overlay is the
+    default.
+  * Move consuming units to screen-registry, so consuming apps can just use:
+
+      import { createScreens } from
+        '@opndev/react-native-events/screen-registry';
+      import { ThemedText } from '@/components/themed-text';
+      import { styles } from '@/styles/tabs';
+
+      const CategoryText =
+        (props) => <ThemedText type="subtitle" {...props} />;
+
+      export const {
+        heroImage,
+        FoodMenuScreen,
+        FoodVendorScreen,
+        HeroScreen,
+        HeroScreenParallax,
+        HeroScreenFixed,
+        NewsItemScreen,
+        NewsListScreen,
+        QRCodeScreen,
+        Tile,
+      } = createScreens({
+        TextComponent: ThemedText,
+        CategoryTextComponent: CategoryText,
+        styles,
+      });
+
 0.0.10       2026-06-21 17:41:27Z
 
   * Rename  @opndev/opndev-react-native-events to  @opndev/react-native-events,

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

@@ -0,0 +1,63 @@
+// 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 { useTopOffset } from './hero-screen-header';
+
+const defaultStyle = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+  },
+});
+
+/**
+ * BaseScreen
+ *
+ * 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. 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
+ * @param {string} [props.backgroundColor]
+ * @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 offset (safe-area inset, or AppScreen bar height if present). Defaults true.
+ *
+ * @returns {JSX.Element}
+ */
+export default function BaseScreen({
+  children,
+  backgroundColor,
+  ContentComponent = ScrollView,
+  containerStyle,
+  contentStyle,
+  useSafeArea = true,
+}) {
+  const topOffset = useTopOffset();
+
+  return (
+    <View
+      style={[
+        defaultStyle.container,
+        backgroundColor ? { backgroundColor } : null,
+        containerStyle,
+      ]}
+    >
+      <ContentComponent
+        style={[defaultStyle.content, contentStyle]}
+        contentContainerStyle={useSafeArea ? { paddingTop: topOffset } : null}
+      >
+        {children}
+      </ContentComponent>
+    </View>
+  );
+}

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

@@ -0,0 +1,105 @@
+// 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,
+  heroContentStyle,
+} from './hero-screen-header';
+
+const defaultStyle = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  headerWrap: {
+    width: '100%',
+    position: 'absolute',
+    top: 0,
+    left: 0,
+  },
+  imageInner: {
+    position: 'absolute',
+    left: 0,
+    width: '100%',
+  },
+});
+
+/**
+ * HeroScreenFixed
+ *
+ * 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. 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
+ * @param {object} [props.headerImage]
+ * @param {React.ReactNode} [props.headerOverlay]
+ * @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 HeroScreenFixed({
+  children,
+  headerImage,
+  headerOverlay,
+  backgroundColor,
+  headerBackgroundColor,
+  headerHeight = 220,
+  ContentComponent = ScrollView,
+  containerStyle,
+  headerStyle,
+  contentStyle,
+}) {
+  const { insetTop, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
+
+  return (
+    <View
+      style={[
+        defaultStyle.container,
+        backgroundColor ? { backgroundColor } : null,
+        containerStyle,
+      ]}
+    >
+      <View
+        style={[
+          defaultStyle.headerWrap,
+          { height: totalHeaderHeight },
+          headerBackgroundColor ? { backgroundColor: headerBackgroundColor } : null,
+          headerStyle,
+        ]}
+      >
+        <View
+          style={[
+            defaultStyle.imageInner,
+            { top: insetTop, height: headerHeight },
+          ]}
+        >
+          {renderHeaderImage(headerImage)}
+        </View>
+      </View>
+
+      <ContentComponent
+        style={{ flex: 1 }}
+        contentContainerStyle={{ paddingTop: totalHeaderHeight }}
+      >
+        <View style={[heroContentStyle, contentStyle]}>
+          <HeaderOverlay headerOverlay={headerOverlay} />
+          {children}
+        </View>
+      </ContentComponent>
+    </View>
+  );
+}

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

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import { View, Image, StyleSheet } from 'react-native';
+import { useAppScreenOffset } from '../hooks/use-app-screen-offset.js';
+
+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 },
+});
+
+export function renderHeaderImage(headerImage) {
+  if (!headerImage) return null;
+  const fit = headerImage.fit || 'cover';
+  const style = headerImage.style || styles.headerImage;
+  return <Image source={headerImage.source} style={style} resizeMode={fit} />;
+}
+
+export function HeaderOverlay({ headerOverlay }) {
+  if (!headerOverlay) return null;
+  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 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 top offset)
+ * @returns {{ topOffset: number, headerHeight: number, totalHeaderHeight: number }}
+ */
+export function useHeroHeaderHeight(headerHeight = 220) {
+  const topOffset = useTopOffset();
+
+  return {
+    topOffset,
+    headerHeight,
+    totalHeaderHeight: topOffset + headerHeight,
+  };
+}
+
+export { styles as heroImageStyles };
+export const heroContentStyle = styles.heroContent;

package/lib/components/hero-screen-parallax.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 { View, StyleSheet } from 'react-native';
+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({
+  children,
+  headerImage,
+  headerOverlay,
+  backgroundColor,
+  headerBackgroundColor,
+  headerHeight,
+  ContentComponent,
+  containerStyle,
+  headerStyle,
+  contentStyle,
+}) {
+  return (
+    <ParallaxScrollView
+      backgroundColor={backgroundColor}
+      headerBackgroundColor={headerBackgroundColor}
+      headerHeight={headerHeight}
+      ContentComponent={ContentComponent}
+      containerStyle={containerStyle}
+      headerStyle={headerStyle}
+      contentStyle={contentStyle}
+      headerImage={
+        <View style={defaultStyle.headerImageWrap}>
+          {renderHeaderImage(headerImage)}
+        </View>
+      }
+    >
+      <HeaderOverlay headerOverlay={headerOverlay} />
+      {children}
+    </ParallaxScrollView>
+  );
+}

package/lib/components/hero-screen.jsx

@@ -2,108 +2,111 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
 
-import { View, StyleSheet, Image } from 'react-native';
-import ParallaxScrollView from './parallax-scroll-view';
+import { View, ScrollView, StyleSheet } from 'react-native';
+import {
+  renderHeaderImage,
+  HeaderOverlay,
+  useHeroHeaderHeight,
+  heroContentStyle,
+} from './hero-screen-header';
 
 const defaultStyle = StyleSheet.create({
-  headerImageWrap: {
+  container: {
+    flex: 1,
+  },
+  headerWrap: {
     width: '100%',
-    height: 220,
-    bottom: 0,
-    left: 0,
     position: 'absolute',
+    top: 0,
+    left: 0,
+    zIndex: 1,
   },
-  headerImage: {
+  imageInner: {
+    position: 'absolute',
+    left: 0,
     width: '100%',
-    height: '100%',
-  },
-  titleWrap: {
-    paddingHorizontal: 8,
-    paddingTop: 8,
-    paddingBottom: 8,
   },
 });
 
 /**
- * HeroScreen
+ * HeroScreenOverlay
  *
- * Thin wrapper around ParallaxScrollView that:
- * - renders a full-bleed header image
- * - renders optional title/header content below the image
- * - renders children below that
+ * Header image stays pinned on top; content scrolls underneath it
+ * (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. Body content is wrapped
+ * the same way ParallaxScrollView wraps its children — padding: 32,
+ * gap: 8 — 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]
- *   Header image config:
- *   - source: React Native image source
- *   - style: optional image style
- *   - fit: optional resize mode, defaults to 'cover'
  * @param {React.ReactNode} [props.headerOverlay]
- *   Optional content rendered below the header image.
  * @param {string} [props.backgroundColor]
  * @param {string} [props.headerBackgroundColor]
- * @param {number} [props.headerHeight]
- * @param {React.ComponentType<{style?: any, children?: React.ReactNode}>}
- *   [props.ContentComponent]
+ * @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 HeroScreen({
+export default function HeroScreenOverlay({
   children,
   headerImage,
   headerOverlay,
-
   backgroundColor,
   headerBackgroundColor,
-  headerHeight,
-
-  ContentComponent,
+  headerHeight = 220,
+  ContentComponent = ScrollView,
   containerStyle,
   headerStyle,
   contentStyle,
 }) {
-  let hi;
-
-  if (headerImage) {
-    const fit = headerImage.fit || 'cover';
-    const style = headerImage.style || defaultStyle.headerImage;
-
-    hi = (
-      <Image
-        source={headerImage.source}
-        style={style}
-        resizeMode={fit}
-      />
-    );
-  }
+  const { topOffset, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
 
   return (
-    <ParallaxScrollView
-      backgroundColor={backgroundColor}
-      headerBackgroundColor={headerBackgroundColor}
-      headerHeight={headerHeight}
-      ContentComponent={ContentComponent}
-      containerStyle={containerStyle}
-      headerStyle={headerStyle}
-      contentStyle={contentStyle}
-      headerImage={
-        <View style={defaultStyle.headerImageWrap}>
-          {hi}
-        </View>
-      }
+    <View
+      style={[
+        defaultStyle.container,
+        backgroundColor ? { backgroundColor } : null,
+        containerStyle,
+      ]}
     >
-      {headerOverlay ? (
-        <View style={defaultStyle.titleWrap}>
-          {headerOverlay}
+      <ContentComponent
+        style={{ flex: 1 }}
+        contentContainerStyle={{ paddingTop: 0 }}
+      >
+        <View style={{ height: totalHeaderHeight }} />
+
+        <View style={[heroContentStyle, contentStyle]}>
+          <HeaderOverlay headerOverlay={headerOverlay} />
+          {children}
         </View>
-      ) : null}
+      </ContentComponent>
 
-      {children}
-    </ParallaxScrollView>
+      <View
+        style={[
+          defaultStyle.headerWrap,
+          { height: totalHeaderHeight },
+          headerBackgroundColor ? { backgroundColor: headerBackgroundColor } : null,
+          headerStyle,
+        ]}
+      >
+        <View
+          style={[
+            defaultStyle.imageInner,
+            { top: topOffset, height: headerHeight },
+          ]}
+        >
+          {renderHeaderImage(headerImage)}
+        </View>
+      </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/qr-code-form.jsx

@@ -179,6 +179,7 @@ export default function QRCodeForm({
   const responseError = getResponseError(response);
   const visibleError = error || responseError;
   const hasResult = Boolean(response && !responseError);
+  const showResponseErrorCard = Boolean(response && responseError);
   const token = hasResult ? action.getToken(response) : undefined;
 
   const renderArgs = {
@@ -297,7 +298,7 @@ export default function QRCodeForm({
    * @returns {JSX.Element|null}
    */
   function renderResult() {
-    if (!hasResult) {
+    if (!hasResult && !showResponseErrorCard) {
       return null;
     }
 
@@ -312,10 +313,10 @@ export default function QRCodeForm({
         ]}
       >
         {renderAboveQRCode ? renderAboveQRCode(renderArgs) : null}
-        {renderQRCode()}
-        {renderBelowQRCode ? renderBelowQRCode(renderArgs) : null}
-        {renderRefreshButton()}
-        {renderResetLink()}
+        {hasResult ? renderQRCode() : null}
+        {hasResult && renderBelowQRCode ? renderBelowQRCode(renderArgs) : null}
+        {hasResult ? renderRefreshButton() : null}
+        {hasResult ? renderResetLink() : renderResetButton()}
       </View>
     );
   }
@@ -390,10 +391,41 @@ export default function QRCodeForm({
   }
 
   /**
+   * Button version of reset, used in place of the link when showing
+   * the error-state card (response.error), so it matches the
+   * success card's button-style affordance instead of a text link.
+   *
+   * @returns {JSX.Element}
+   */
+  function renderResetButton() {
+    return (
+      <Pressable
+        style={[
+          defaultStyle.button,
+          defaultStyle.wideButton,
+          secondaryButtonBackgroundColor
+            ? { backgroundColor: secondaryButtonBackgroundColor }
+            : null,
+          secondaryButtonStyle,
+        ]}
+        onPress={reset}
+      >
+        <TextComponent style={secondaryButtonTextStyle}>
+          {resetLabel}
+        </TextComponent>
+      </Pressable>
+    );
+  }
+
+  /**
+   * Only handles the network/throw-style error (from the catch block
+   * in fetchQr). Response-level errors (response.error) are now
+   * rendered inside renderResult() as a styled card instead.
+   *
    * @returns {JSX.Element|null}
    */
   function renderError() {
-    if (!visibleError) {
+    if (!error) {
       return null;
     }
 
@@ -412,10 +444,8 @@ export default function QRCodeForm({
             errorTextStyle,
           ]}
         >
-          {visibleError}
+          {error}
         </TextComponent>
-
-        {responseError ? renderResetLink() : null}
       </View>
     );
   }

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

@@ -0,0 +1,20 @@
+// 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';
+
+/**
+ * useSafeAreaTopInset
+ *
+ * Single source of truth for "how much space does the status bar /
+ * notch take up". Used by both HeroScreen variants (via
+ * useHeroHeaderHeight) and plain Screen, so every screen in the
+ * package agrees on the same number.
+ *
+ * @returns {number}
+ */
+export function useSafeAreaTopInset() {
+  const insets = useSafeAreaInsets();
+  return insets.top;
+}

package/lib/index.js

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

package/lib/screen-registry.js

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+import React from 'react';
+
+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';
+import FoodVendorScreen from './screens/food-vendor-screen';
+import NewsItemScreen from './screens/news-item-screen';
+import NewsListScreen from './screens/news-list-screen';
+import QRCodeScreen from './screens/qr-code-screen';
+
+/**
+ * createScreens
+ *
+ * @param {object} [options]
+ * @param {React.ComponentType} [options.TextComponent]
+ * @param {React.ComponentType} [options.CategoryTextComponent]
+ * @param {object} [options.styles]
+ *   App-provided style object. Used as the default source for
+ *   heroImage() when a caller doesn't pass an explicit style/fit.
+ *   Expected (optional) keys: heroImage, heroImageFit.
+ *
+ * @returns {object} Named screens + helpers, ready to re-export.
+ */
+export function createScreens({
+  TextComponent,
+  CategoryTextComponent,
+  styles = {},
+} = {}) {
+  /**
+   * heroImage
+   *
+   * @param {any} source
+   * @param {object} [options]
+   * @param {object} [options.style]
+   * @param {string} [options.fit] // 'cover', 'contain', etc
+   */
+  function heroImage(source, options = {}) {
+    return {
+      source,
+      style: options.style || styles.heroImage,
+      fit: options.fit || styles.heroImageFit,
+    };
+  }
+
+  return {
+    heroImage,
+
+    HeroScreen: (props) => (
+      <HeroScreen {...props} />
+    ),
+
+    HeroScreenParallax: (props) => (
+      <HeroScreenParallax {...props} />
+    ),
+
+    HeroScreenFixed: (props) => (
+      <HeroScreenFixed {...props} />
+    ),
+
+    HeroScreenOverlay: (props) => (
+      <HeroScreenOverlay {...props} />
+    ),
+
+    Screen: (props) => (
+      <Screen {...props} />
+    ),
+
+    AppScreen: (props) => (
+      <AppScreen {...props} />
+    ),
+
+    AppScreenTopBar: (props) => (
+      <AppScreenTopBar {...props} />
+    ),
+
+    FoodMenuScreen: (props) => (
+      <FoodMenuScreen
+        {...props}
+        TextComponent={TextComponent}
+        CategoryTextComponent={CategoryTextComponent}
+      />
+    ),
+
+    FoodVendorScreen: (props) => (
+      <FoodVendorScreen
+        {...props}
+        TextComponent={TextComponent}
+      />
+    ),
+
+    QRCodeScreen: (props) => (
+      <QRCodeScreen
+        {...props}
+        TextComponent={TextComponent}
+      />
+    ),
+
+    NewsListScreen: (props) => (
+      <NewsListScreen
+        {...props}
+        TextComponent={TextComponent}
+      />
+    ),
+
+    NewsItemScreen: (props) => (
+      <NewsItemScreen
+        {...props}
+        TextComponent={TextComponent}
+      />
+    ),
+
+    Tile: (props) => (
+      <Tile
+        {...props}
+        TextComponent={TextComponent}
+      />
+    ),
+  };
+}

package/package.json

@@ -11,12 +11,13 @@
   "exports": {
     ".": "./lib/index.js",
     "./components": "./lib/components.js",
-    "./globals": "./lib/screen-registery.js",
-    "./hero-screen-registry": "./lib/hero-screen-registery.js",
-    "./lite": "./lib/hero-screen-registery.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-registery": "./lib/screen-registery.js",
+    "./screen-registry": "./lib/screen-registry.js",
     "./screens": "./lib/screens.js"
   },
   "keywords": [],
@@ -33,5 +34,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.10"
+  "version": "0.0.12"
 }

package/lib/screen-registery.js

@@ -1,68 +0,0 @@
-// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
-//
-// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
-
-import React from 'react';
-
-import HeroScreen from './components/hero-screen';
-import Tile from './components/tile';
-
-import FoodMenuScreen from './screens/food-menu-screen';
-import FoodVendorScreen from './screens/food-vendor-screen';
-import NewsItemScreen from './screens/news-item-screen';
-import NewsListScreen from './screens/news-list-screen';
-import QRCodeScreen from './screens/qr-code-screen';
-
-export function createScreens({
-  TextComponent,
-  CategoryTextComponent,
-} = {}) {
-  return {
-    HeroScreen: (props) => (
-      <HeroScreen {...props} />
-    ),
-
-    FoodMenuScreen: (props) => (
-      <FoodMenuScreen
-        {...props}
-        TextComponent={TextComponent}
-        CategoryTextComponent={CategoryTextComponent}
-      />
-    ),
-
-    FoodVendorScreen: (props) => (
-      <FoodVendorScreen
-        {...props}
-        TextComponent={TextComponent}
-      />
-    ),
-
-    QRCodeScreen: (props) => (
-      <QRCodeScreen
-        {...props}
-        TextComponent={TextComponent}
-      />
-    ),
-
-    NewsListScreen: (props) => (
-      <NewsListScreen
-        {...props}
-        TextComponent={TextComponent}
-      />
-    ),
-
-    NewsItemScreen: (props) => (
-      <NewsItemScreen
-        {...props}
-        TextComponent={TextComponent}
-      />
-    ),
-
-    Tile: (props) => (
-      <Tile
-        {...props}
-        TextComponent={TextComponent}
-      />
-    ),
-  };
-}