@opndev/react-native-events 0.0.11 → 0.0.12

package/Changes

@@ -1,5 +1,10 @@
 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 :/

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,9 +1,16 @@
+// 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 { useSafeAreaTopInset } from '../hooks/use-safe-area-top-inset.js';
+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) {
@@ -18,24 +25,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,8 @@ import { View, ScrollView, StyleSheet } from 'react-native';
 import {
   renderHeaderImage,
   HeaderOverlay,
-  useHeroHeaderHeight
+  useHeroHeaderHeight,
+  heroContentStyle,
 } from './hero-screen-header';
 
 const defaultStyle = StyleSheet.create({
@@ -34,7 +35,12 @@ 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: 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
@@ -62,7 +68,7 @@ export default function HeroScreenOverlay({
   headerStyle,
   contentStyle,
 }) {
-  const { insetTop, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
+  const { topOffset, totalHeaderHeight } = useHeroHeaderHeight(headerHeight);
 
   return (
     <View
@@ -73,12 +79,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,7 +101,7 @@ export default function HeroScreenOverlay({
         <View
           style={[
             defaultStyle.imageInner,
-            { top: insetTop, height: headerHeight },
+            { top: topOffset, height: headerHeight },
           ]}
         >
           {renderHeaderImage(headerImage)}

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.12";
 
 // 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/package.json

@@ -34,5 +34,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.11"
+  "version": "0.0.12"
 }