@opndev/react-native-events 0.0.16 → 0.0.17

package/Changes

@@ -1,5 +1,11 @@
 Revision history for @opndev/opndev-react-native-events
 
+0.0.17       2026-06-28 04:29:54Z
+
+  * Add gradient panel and proper implementation of contrast color, not just
+    "pick white or black"
+  * Fix HeroScreenFixed to be actually fixed to the content
+
 0.0.16       2026-06-27 23:25:11Z
 
   * Add widgets for dynamic and static content:

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

@@ -15,11 +15,8 @@ const defaultStyle = StyleSheet.create({
   container: {
     flex: 1,
   },
-  headerWrap: {
+  header: {
     width: '100%',
-    position: 'absolute',
-    top: 0,
-    left: 0,
   },
   imageInner: {
     position: 'absolute',
@@ -31,12 +28,24 @@ const defaultStyle = StyleSheet.create({
 /**
  * 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.
+ * Header image is a normal, in-flow element at the top of the
+ * scroll — it scrolls away together with the content below it, at
+ * the same rate, with no pinning and no animation. Same structural
+ * shape as HeroScreenParallax, just without the scroll-driven
+ * scale/translateY transform — "parallax minus the animation."
+ *
+ * "Fixed" means fixed to the content below it, not fixed to the
+ * screen — the previous version of this file pinned the header via
+ * position:absolute, which was actually the same idea as
+ * HeroScreenOverlay, not what "Fixed" was meant to mean. Rebuilt
+ * from scratch; this file had no usages anywhere yet.
+ *
+ * ContentComponent's role matches HeroScreenParallax's: it wraps
+ * the body content for layout purposes (defaults to View, NOT a
+ * scroll container) — the actual scrolling is owned by the outer
+ * ScrollView, hardcoded, not swappable. If you were expecting
+ * ContentComponent to default to ScrollView (the old behavior),
+ * that's the one real API change here.
  *
  * @param {object} props
  * @param {React.ReactNode} props.children Normal body content, and/or <CarouselScreen> elements for slides.
@@ -48,7 +57,7 @@ const defaultStyle = StyleSheet.create({
  * @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 {React.ComponentType} [props.ContentComponent] Defaults to View — wraps body content, does NOT own scrolling.
  * @param {object} [props.containerStyle]
  * @param {object} [props.headerStyle]
  * @param {object} [props.contentStyle]
@@ -65,7 +74,7 @@ export default function HeroScreenFixed({
   backgroundColor,
   headerBackgroundColor,
   headerHeight = 220,
-  ContentComponent = ScrollView,
+  ContentComponent = View,
   containerStyle,
   headerStyle,
   contentStyle,
@@ -74,7 +83,7 @@ export default function HeroScreenFixed({
   const { slideElements, bodyChildren } = splitCarouselChildren(children);
 
   return (
-    <View
+    <ScrollView
       style={[
         defaultStyle.container,
         backgroundColor ? { backgroundColor } : null,
@@ -83,7 +92,7 @@ export default function HeroScreenFixed({
     >
       <View
         style={[
-          defaultStyle.headerWrap,
+          defaultStyle.header,
           { height: totalHeaderHeight },
           headerBackgroundColor ? { backgroundColor: headerBackgroundColor } : null,
           headerStyle,
@@ -105,15 +114,10 @@ export default function HeroScreenFixed({
         </View>
       </View>
 
-      <ContentComponent
-        style={{ flex: 1 }}
-        contentContainerStyle={{ paddingTop: totalHeaderHeight }}
-      >
-        <View style={[heroContentStyle, contentStyle]}>
-          <HeaderOverlay headerOverlay={headerOverlay} />
-          {bodyChildren}
-        </View>
+      <ContentComponent style={[heroContentStyle, contentStyle]}>
+        <HeaderOverlay headerOverlay={headerOverlay} />
+        {bodyChildren}
       </ContentComponent>
-    </View>
+    </ScrollView>
   );
 }

package/lib/components/panel-gradient.jsx

@@ -0,0 +1,150 @@
+import React from 'react';
+import { View, Pressable, StyleSheet } from 'react-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { contrastColor } from '../utils/colors';
+import { PanelContrastContext } from '../hooks/use-panel-contrast';
+
+// Six named directions — end is always the geometric opposite of
+// start, so only one end of each axis needs naming. Want the
+// reverse (e.g. bottom-left to top-right)? Swap the order of
+// `colors` instead of asking for a 7th/8th direction keyword.
+const DIRECTIONS = {
+  top: { start: { x: 0, y: 0 }, end: { x: 0, y: 1 } },
+  bottom: { start: { x: 0, y: 1 }, end: { x: 0, y: 0 } },
+  left: { start: { x: 0, y: 0 }, end: { x: 1, y: 0 } },
+  right: { start: { x: 1, y: 0 }, end: { x: 0, y: 0 } },
+  'top-left': { start: { x: 0, y: 0 }, end: { x: 1, y: 1 } },
+  'top-right': { start: { x: 1, y: 0 }, end: { x: 0, y: 1 } },
+};
+
+// Local for now, not added to lib/utils/colors.js since I haven't
+// seen that file's full current content — move it there later if
+// you want it shared. Only handles 6-digit hex (#RRGGBB); named
+// colors ('white') or rgba() strings aren't parsed.
+function hexToRgb(hex) {
+  const clean = hex.replace('#', '');
+  const value = parseInt(clean, 16);
+  return { r: (value >> 16) & 255, g: (value >> 8) & 255, b: value & 255 };
+}
+
+function rgbToHex({ r, g, b }) {
+  return '#' + [r, g, b].map((v) => Math.round(v).toString(16).padStart(2, '0')).join('');
+}
+
+function averageColor(colors) {
+  const rgbs = colors.map(hexToRgb);
+  const sum = rgbs.reduce((acc, c) => ({ r: acc.r + c.r, g: acc.g + c.g, b: acc.b + c.b }), { r: 0, g: 0, b: 0 });
+  const n = rgbs.length;
+  return rgbToHex({ r: sum.r / n, g: sum.g / n, b: sum.b / n });
+}
+
+const defaultStyle = StyleSheet.create({
+  shadowWrap: {
+    borderRadius: 16,
+  },
+  shadowOn: {
+    elevation: 4,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.15,
+    shadowRadius: 6,
+  },
+  surface: {
+    borderRadius: 16,
+    overflow: 'hidden',
+  },
+  content: {
+    padding: 16,
+  },
+});
+
+/**
+ * GradientPanel
+ *
+ * Same shape and behavior as Panel — sizes to its content, no
+ * forced layout on children, same shadow-split structure (an outer
+ * shadow-casting view, an inner clipping view, for the same reason
+ * Panel needs it: a shadow renders outside a view's own bounds, so
+ * it can't live on the same view that clips with overflow:hidden).
+ *
+ * The only difference: a gradient background instead of a flat
+ * `backgroundColor`. Stays theme-agnostic like Panel — pass raw
+ * resolved colors (e.g. ['#FFFFFF', theme.primary]), this component
+ * doesn't reach into your theme itself.
+ *
+ * Automatically derives a contrast text color from the AVERAGE of
+ * its `colors` stops (via contrastColor — same hue/saturation,
+ * contrasting lightness, not flat black/white), made available to
+ * anything rendered inside via PanelContrastContext — same
+ * mechanism Panel uses. This is a heuristic, not exact — a fade
+ * from white to a dark color averages to something mid-tone, which
+ * may not actually read well at either literal end of the gradient.
+ * Override with `contrastTextColor` if the heuristic guesses wrong.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children
+ * @param {string[]} [props.colors] Gradient stops, e.g. ['#FFFFFF', theme.primary]. Defaults to ['#FFFFFF', '#FFFFFF'] (solid white) if omitted.
+ * @param {'top'|'bottom'|'left'|'right'|'top-left'|'top-right'} [props.direction] Defaults to 'top'. Takes precedence over start/end if both are given.
+ * @param {{x: number, y: number}} [props.start] Raw escape hatch, ignored if `direction` is set.
+ * @param {{x: number, y: number}} [props.end] Raw escape hatch, ignored if `direction` is set.
+ * @param {number[]} [props.locations] Where each color stop lands (0-1). Optional — omit for an even spread.
+ * @param {string} [props.contrastTextColor] Overrides the automatically-derived (average-based) contrast color.
+ * @param {boolean} [props.shadow] Floating-card drop shadow. Defaults to false.
+ * @param {Function} [props.onPress] If provided, the whole panel becomes pressable.
+ * @param {object} [props.style] Style for the outer (shadow-casting) wrapper.
+ * @param {object} [props.contentStyle] Style for the inner content wrapper (default padding: 16).
+ *
+ * @returns {JSX.Element}
+ */
+export default function GradientPanel({
+  children,
+  colors = ['#FFFFFF', '#FFFFFF'],
+  direction = 'top',
+  start,
+  end,
+  locations,
+  contrastTextColor,
+  shadow = false,
+  onPress,
+  style,
+  contentStyle,
+}) {
+  const resolvedDirection = DIRECTIONS[direction] ?? {
+    start: start ?? DIRECTIONS.top.start,
+    end: end ?? DIRECTIONS.top.end,
+  };
+  const resolvedContrast = contrastTextColor ?? contrastColor(averageColor(colors));
+
+  const content = (
+    <LinearGradient
+      colors={colors}
+      start={resolvedDirection.start}
+      end={resolvedDirection.end}
+      locations={locations}
+      style={defaultStyle.surface}
+    >
+      <PanelContrastContext.Provider value={resolvedContrast}>
+        <View style={[defaultStyle.content, contentStyle]}>
+          {children}
+        </View>
+      </PanelContrastContext.Provider>
+    </LinearGradient>
+  );
+
+  const wrapperStyle = [
+    defaultStyle.shadowWrap,
+    shadow ? defaultStyle.shadowOn : null,
+    shadow ? { backgroundColor: colors[0] } : null,
+    style,
+  ];
+
+  if (onPress) {
+    return (
+      <Pressable onPress={onPress} style={wrapperStyle}>
+        {content}
+      </Pressable>
+    );
+  }
+
+  return <View style={wrapperStyle}>{content}</View>;
+}

package/lib/components/panel.jsx

@@ -1,9 +1,10 @@
 // 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 { View, Pressable, StyleSheet } from 'react-native';
+import { contrastColor } from '../utils/colors';
+import { PanelContrastContext } from '../hooks/use-panel-contrast';
 
 const defaultStyle = StyleSheet.create({
   shadowWrap: {
@@ -43,9 +44,19 @@ const defaultStyle = StyleSheet.create({
  * split means `shadow` can be toggled on/off with no other changes
  * needed, and panels that don't use it are unaffected.
  *
+ * Automatically derives a contrast text color from `backgroundColor`
+ * (via contrastColor) and makes it available to anything rendered
+ * inside, via PanelContrastContext — so e.g. DataListWidget picks up
+ * a correct default text color for whatever Panel it's sitting in,
+ * with zero per-usage color wiring. Pass `contrastTextColor`
+ * yourself to override the automatic guess; anything inside can
+ * still override further for individual pieces of text (e.g.
+ * DataListWidget's own itemTextStyle/titleStyle still win over this).
+ *
  * @param {object} props
  * @param {React.ReactNode} props.children
  * @param {string} [props.backgroundColor]
+ * @param {string} [props.contrastTextColor] Overrides the automatically-derived contrast color.
  * @param {boolean} [props.shadow] Floating-card drop shadow. Defaults to false.
  * @param {Function} [props.onPress] If provided, the whole panel becomes pressable.
  * @param {object} [props.style] Style for the outer (shadow-casting) wrapper.
@@ -56,20 +67,26 @@ const defaultStyle = StyleSheet.create({
 export default function Panel({
   children,
   backgroundColor,
+  contrastTextColor,
   shadow = false,
   onPress,
   style,
   contentStyle,
 }) {
+  const resolvedContrast = contrastTextColor
+    ?? (backgroundColor ? contrastColor(backgroundColor) : null);
+
   const surfaceStyle = [
     defaultStyle.surface,
     backgroundColor ? { backgroundColor } : null,
   ];
 
   const content = (
-    <View style={[defaultStyle.content, contentStyle]}>
-      {children}
-    </View>
+    <PanelContrastContext.Provider value={resolvedContrast}>
+      <View style={[defaultStyle.content, contentStyle]}>
+        {children}
+      </View>
+    </PanelContrastContext.Provider>
   );
 
   const inner = onPress ? (

package/lib/components.js

@@ -12,6 +12,7 @@ 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 { default as Panel } from './components/panel.jsx';
+export { default as GradientPanel } from './components/panel-gradient.jsx';
 
 export { openUrl, openApp, openExternal } from './utils/launch.js';
 

package/lib/hooks/use-panel-contrast.js

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * PanelContrastContext
+ *
+ * Provided by Panel — the contrast color automatically derived from
+ * its backgroundColor (or a manual override, if Panel was given
+ * one). Defaults to null, so anything reading this outside a Panel
+ * just gets "no opinion," not a wrong color.
+ */
+export const PanelContrastContext = createContext(null);
+
+/**
+ * usePanelContrast
+ *
+ * @returns {string|null} The enclosing Panel's contrast color, or null if there isn't one.
+ */
+export function usePanelContrast() {
+  return useContext(PanelContrastContext);
+}

package/lib/index.js

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

package/lib/utils/colors.js

@@ -18,19 +18,15 @@
 export function mixHexColors(a, b, amount = 0.5) {
   const ah = a.replace('#', '');
   const bh = b.replace('#', '');
-
   const ar = parseInt(ah.slice(0, 2), 16);
   const ag = parseInt(ah.slice(2, 4), 16);
   const ab = parseInt(ah.slice(4, 6), 16);
-
   const br = parseInt(bh.slice(0, 2), 16);
   const bg = parseInt(bh.slice(2, 4), 16);
   const bb = parseInt(bh.slice(4, 6), 16);
-
   const r = Math.round(ar + (br - ar) * amount);
   const g = Math.round(ag + (bg - ag) * amount);
   const b2 = Math.round(ab + (bb - ab) * amount);
-
   return (
     '#' +
     r.toString(16).padStart(2, '0') +
@@ -40,27 +36,116 @@ export function mixHexColors(a, b, amount = 0.5) {
 }
 
 /**
- * Return black or white depending on which has better contrast.
+ * Convert a hex color to HSL.
+ *
+ * @param {string} hex
+ *   Color as "#rrggbb".
+ *
+ * @returns {{h: number, s: number, l: number}}
+ *   Each in the 0-1 range (h is fraction of 360°, not degrees).
+ */
+function hexToHsl(hex) {
+  const value = hex.replace('#', '');
+  const r = parseInt(value.slice(0, 2), 16) / 255;
+  const g = parseInt(value.slice(2, 4), 16) / 255;
+  const b = parseInt(value.slice(4, 6), 16) / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+
+  let h = 0;
+  let s = 0;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+    switch (max) {
+      case r:
+        h = (g - b) / d + (g < b ? 6 : 0);
+        break;
+      case g:
+        h = (b - r) / d + 2;
+        break;
+      default:
+        h = (r - g) / d + 4;
+        break;
+    }
+    h /= 6;
+  }
+
+  return { h, s, l };
+}
+
+/**
+ * Convert HSL back to a hex color.
+ *
+ * @param {{h: number, s: number, l: number}} hsl
+ *   Each in the 0-1 range (h is fraction of 360°, not degrees).
+ *
+ * @returns {string}
+ *   Color as "#rrggbb".
+ */
+function hslToHex({ h, s, l }) {
+  function hueToRgb(p, q, t) {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  }
+
+  let r;
+  let g;
+  let b;
+
+  if (s === 0) {
+    r = g = b = l;
+  }
+  else {
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    r = hueToRgb(p, q, h + 1 / 3);
+    g = hueToRgb(p, q, h);
+    b = hueToRgb(p, q, h - 1 / 3);
+  }
+
+  const toHex = (c) => Math.round(c * 255).toString(16).padStart(2, '0');
+  return '#' + toHex(r) + toHex(g) + toHex(b);
+}
+
+/**
+ * Return a contrasting color in the SAME hue/saturation family as
+ * the input, just pushed to a very different lightness — the same
+ * technique CSS color-ramp design systems use (Tailwind/Radix-style
+ * 50-950 scales): same color family, different shade, rather than
+ * jumping to flat black/white. A light, desaturated input still
+ * gets a colored (just very dark) result; a fully neutral input
+ * (pure white/black/gray, s=0) naturally falls back to plain
+ * gray at the target lightness, since there's no hue to preserve.
  *
  * @param {string} hex
  *   Background color as "#rrggbb".
  *
  * @returns {string}
- *   "#000000" or "#ffffff".
+ *   A same-hue, contrasting-lightness hex color.
  */
 export function contrastColor(hex) {
   const value = hex.replace('#', '');
-
   const r = parseInt(value.slice(0, 2), 16) / 255;
   const g = parseInt(value.slice(2, 4), 16) / 255;
   const b = parseInt(value.slice(4, 6), 16) / 255;
-
   const luminance =
     0.2126 * toLinear(r) +
     0.7152 * toLinear(g) +
     0.0722 * toLinear(b);
 
-  return luminance > 0.179 ? '#000000' : '#ffffff';
+  const { h, s } = hexToHsl(hex);
+  const targetLightness = luminance > 0.179 ? 0.15 : 0.92;
+
+  return hslToHex({ h, s, l: targetLightness });
 }
 
 /**
@@ -76,7 +161,5 @@ export function toLinear(channel) {
   if (channel <= 0.03928) {
     return channel / 12.92;
   }
-
   return ((channel + 0.055) / 1.055) ** 2.4;
 }
-

package/lib/widgets/data-list-widget.jsx

@@ -10,6 +10,7 @@ import {
   View,
 } from 'react-native';
 import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
+import { usePanelContrast } from '../hooks/use-panel-contrast';
 
 const defaultStyle = StyleSheet.create({
   container: {
@@ -111,6 +112,19 @@ export default function DataListWidget({
   errorTextStyle,
 }) {
   const showTitleRow = title || showRefreshButton;
+  const panelContrast = usePanelContrast();
+  const contrastTextStyle = panelContrast ? { color: panelContrast } : null;
+
+  if (__DEV__ && !loading && !error && items.length) {
+    items.forEach((item, index) => {
+      if (item == null || item.id == null || item.title == null) {
+        throw new Error(
+          `DataListWidget: item at index ${index} is missing "id" or "title". ` +
+          `Check that mapItem returns { id, title, description? } — got: ${JSON.stringify(item)}`
+        );
+      }
+    });
+  }
 
   return (
     <View
@@ -127,7 +141,7 @@ export default function DataListWidget({
           ]}
         >
           {title ? (
-            <TextComponent style={[defaultStyle.title, titleStyle]}>
+            <TextComponent style={[defaultStyle.title, contrastTextStyle, titleStyle]}>
               {title}
             </TextComponent>
           ) : null}
@@ -169,14 +183,14 @@ export default function DataListWidget({
           onPress={() => onPressItem?.(item)}
         >
           {showBullet ? (
-            <TextComponent style={[defaultStyle.bullet, itemTextStyle]}>{'\u2022'}</TextComponent>
+            <TextComponent style={[defaultStyle.bullet, contrastTextStyle, itemTextStyle]}>{'\u2022'}</TextComponent>
           ) : null}
           <View style={defaultStyle.itemBody}>
-            <TextComponent style={itemTextStyle}>
+            <TextComponent style={[contrastTextStyle, itemTextStyle]}>
               {item.title}
             </TextComponent>
             {item.description ? (
-              <TextComponent style={descriptionStyle}>
+              <TextComponent style={[contrastTextStyle, descriptionStyle]}>
                 {item.description}
               </TextComponent>
             ) : null}
@@ -186,4 +200,3 @@ export default function DataListWidget({
     </View>
   );
 }
-

package/package.json

@@ -35,5 +35,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.16"
+  "version": "0.0.17"
 }