@opndev/react-native-events 0.0.10

package/README.md

@@ -0,0 +1,320 @@
+<!--
+SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+
+SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+-->
+
+# Welcome to @opndev/opndev-react-native-events
+
+Reusable React Native / Expo components for event-style apps.
+
+Focus:
+- fast to build
+- minimal dependencies
+- reusable across projects
+- no app-specific assumptions
+
+This package provides a small set of building blocks for:
+
+- hero / parallax screens
+- vendor grids
+- menu-style content
+- tile-based navigation
+- external link / app launching
+
+## Installation
+
+```bash
+npm install @opndev/opndev-react-native-events
+```
+
+Peer dependencies are expected to be installed by the consuming app.
+
+## Components
+
+### HeroScreen
+
+Base layout for screens with:
+- parallax header image
+- optional overlay (title, back button, etc)
+- scrollable content
+
+```jsx
+<HeroScreen
+  headerImage={<Image ... />}
+  headerOverlay={<Text>Title</Text>}
+>
+  {children}
+</HeroScreen>
+```
+
+### ParallaxScrollView
+
+Low-level scroll + animation component used by `HeroScreen`.
+
+Theme-agnostic. Consumers inject:
+- colors
+- content wrapper
+- styling overrides
+
+### FoodVendorScreen
+
+Grid of vendor tiles.
+
+```jsx
+<FoodVendorScreen
+  title="Food vendors"
+  headerImage={<Image ... />}
+  vendors={[
+    { key: 'bar', label: 'Bar' },
+  ]}
+  onSelectVendor={(vendor) => {
+    // navigation handled by app
+  }}
+/>
+```
+
+### FoodMenuScreen
+
+Menu-style screen with categories and items.
+
+```jsx
+<FoodMenuScreen
+  title="Bar"
+  headerImage={<Image ... />}
+  menu={vendor.menu}
+  onBack={() => router.back()}
+/>
+```
+
+### Tile / GradientTile
+
+Reusable tile components.
+
+```jsx
+<Tile
+  label="Info"
+  onPress={...}
+/>
+
+<GradientTile
+  label="Bar"
+  colors={['#F4D645', '#9FDEED']}
+  onPress={...}
+/>
+```
+
+## QR Code Screen
+
+A generic, configurable QR code form + result screen.
+
+### Basic Usage
+
+```jsx
+<QrCodeScreen
+  TextComponent={Text}
+  endpoint={endpoint}
+  fields={fields}
+  title="Check-in QR"
+
+  renderAboveQRCode={renderAboveQRCode}
+  renderBelowQRCode={renderBelowQRCode}
+
+  successButtons={['refresh', 'reset', 'back']}
+  onBack={() => navigation.goBack()}
+/>
+```
+
+### Data Contract
+
+```json
+{
+  "token": "...",
+  "status": "pending",
+  "error": null
+}
+```
+
+- HTTP always returns 200
+- logical errors come via `error`
+- component treats `error` as failure
+
+### Render Hooks
+
+#### renderAboveQRCode
+
+```jsx
+const renderAboveQRCode = ({ response }) => {
+  if (response.status !== 'pending') {
+    return null;
+  }
+
+  return (
+    <>
+      <Text>Awaiting Check-in</Text>
+      <Text>Present this QR code at the entry desk</Text>
+    </>
+  );
+};
+```
+
+#### renderBelowQRCode
+
+```jsx
+const renderBelowQRCode = ({ fields, values }) => {
+  return (
+    <View>
+      {fields.map((field) => (
+        <View key={field.key}>
+          <Text>{field.label}:</Text>
+          <Text>{values[field.key]}</Text>
+        </View>
+      ))}
+    </View>
+  );
+};
+```
+
+### Multi-step Status Example
+
+```jsx
+const steps = [
+  { key: 'pending', label: 'Pending' },
+  { key: 'checked_in', label: 'Checked-in' },
+  { key: 'goodie_bag_received', label: 'Goodie-bag-received' },
+];
+
+const renderAboveQRCode = ({ response }) => {
+  const currentIndex = steps.findIndex(
+    (step) => step.key === response.status
+  );
+
+  return (
+    <>
+      <Text>Event Status</Text>
+      <View>
+        {steps.map((step, idx) => {
+          const isCurrent = idx === currentIndex;
+          const isDone = idx < currentIndex;
+
+          return (
+            <Text key={step.key}>
+              {step.label}
+              {isCurrent ? ' (current)' : ''}
+              {isDone ? ' (done)' : ''}
+            </Text>
+          );
+        })}
+      </View>
+    </>
+  );
+};
+```
+
+### Success Buttons
+
+```jsx
+successButtons={['refresh', 'reset', 'back']}
+```
+
+Supported:
+- refresh
+- reset
+- back
+
+Default:
+```jsx
+['refresh', 'reset']
+```
+
+### Responsibilities
+
+Component:
+- form state
+- persistence
+- API calls
+- error handling
+- QR rendering
+- success actions
+
+Caller:
+- status UI
+- layout above/below QR
+- mapping status to UI
+
+## Utils
+
+### openExternal
+
+Helper for opening:
+- URLs
+- apps (deep links)
+- Play Store / App Store fallback
+
+```js
+import { openExternal } from '@opndev/opndev-react-native-events';
+
+openExternal({
+  url: 'instagram://user?username=...',
+  packageName: 'com.instagram.android',
+  appStoreUrl: 'https://apps.apple.com/app/instagram',
+});
+```
+
+Internal navigation is intentionally **not handled** by this package.
+
+## Development
+
+Try to keep functions small and try not to depend on any outside functions. We
+aim to keep the dependency graph as small as possible. The use of `esm` is
+welcomed and writing tests is encouraged.
+
+### jsdoc
+
+You can build the documentation by running `npm run jsdoc`.
+
+### eslint
+
+The ES Linting profile is flexible and does not try to enforce much. There is
+more than one way to do it ([TIMTOWTDI](https://en.wikipedia.org/wiki/There%27s_more_than_one_way_to_do_it)).
+
+Try to stay constistent, but forcing a programming style upon others is bad.
+
+## Code of Conduct
+
+Be human.
+
+## Semver
+
+This project does not adhere to semver and one should not rely on the version
+x.y.z notation to infer stability or reliability. Read the Changes file to see
+any updates a version may bring. The fact that this module sits currently at
+0.x.z ranges does not indicate alpha or beta or even unstable associations. It
+is just a number and we started at 0.0.1.
+
+In general the following hard guarantee will be given: We will not break your
+code. In case we do happen to cause breakage: we will fix it accordingly.
+
+In case we foresee breaking changes we'll add deprecation warnings. Giving you
+time to fix things before a breaking change will be introduced. When a change
+will be introduced is communicated in the Changes file. Security fixes may
+cause breakage at any given time without notice.
+
+This package is released by `@opndev/rzilla`, changes to `package.json` will be
+overridden. In addition to a little bit of promotion, this also means that
+version numbers are autoincremented at release time and bumped in all relevant
+files: Versioning for humans, not machines.
+
+
+### License
+
+Please be aware that this package is GPL-3.0-or-later with exceptions. Please
+refer to the LICENSES directory for more on this.
+
+### Code contributions
+
+This project does not accept pull, merge or patches from others.
+
+Due to the license and how copyright law works, this module will not accept
+code written by people who are not employed by opndev.io.

package/lib/actions/news.js

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+/**
+ * News API cache time-to-live.
+ */
+const TTL_MS = 15 * 60 * 1000;
+
+/**
+ * In-memory cache for news API responses.
+ */
+const cache = new Map();
+
+/**
+ * Builds a cache key for a given URI and bearer token.
+ *
+ * @param {string} uri
+ * @param {string} [bearerToken]
+ *
+ * @returns {string}
+ */
+function getCacheKey(uri, bearerToken) {
+  return `${uri}::${bearerToken || ''}`;
+}
+
+/**
+ * Returns true when a cache entry is still fresh.
+ *
+ * @param {object} entry
+ *
+ * @returns {boolean}
+ */
+function isFresh(entry) {
+  if (!entry) {
+    return false;
+  }
+
+  return (Date.now() - entry.fetchedAt) < TTL_MS;
+}
+
+/**
+ * Fetches JSON from the news API with optional bearer token support.
+ *
+ * Cached responses are reused for 15 minutes unless `force` is set.
+ *
+ * @param {object} args
+ * @param {string} args.uri
+ * @param {string} [args.bearerToken]
+ * @param {boolean} [args.force]
+ *
+ * @returns {Promise<any>}
+ */
+export async function fetchNewsJson({
+  uri,
+  bearerToken,
+  force = false,
+}) {
+  const key = getCacheKey(uri, bearerToken);
+  const entry = cache.get(key);
+
+  if (!force && isFresh(entry)) {
+    return entry.data;
+  }
+
+  const headers = {};
+  if (bearerToken) {
+    headers.Authorization = `Bearer ${bearerToken}`;
+  }
+
+  const res = await fetch(uri, {
+    method: 'GET',
+    headers,
+  });
+
+  const data = await res.json();
+
+  cache.set(key, {
+    data,
+    fetchedAt: Date.now(),
+  });
+
+  return data;
+}
+
+/**
+ * Clears the cached response for a specific URI.
+ *
+ * @param {object} args
+ * @param {string} args.uri
+ * @param {string} [args.bearerToken]
+ *
+ * @returns {void}
+ */
+export function clearNewsCache({
+  uri,
+  bearerToken,
+}) {
+  cache.delete(getCacheKey(uri, bearerToken));
+}

package/lib/actions/qrcode.js

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later WITH LicenseRef-OPNDEV-exceptions
+
+/**
+ * QRCodeAction
+ *
+ * Small helper for QR form persistence + request handling.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export default class QRCodeAction {
+
+  /**
+   * @param {object} props
+   * @param {{url: string, method?: string, headers?: object}} props.endpoint
+   * @param {string} [props.storageKey]
+   * @param {(values: object) => any} [props.buildPayload]
+   * @param {(response: any) => string} [props.extractToken]
+   */
+  constructor({
+    endpoint,
+    storageKey = 'qr-form',
+    buildPayload,
+    extractToken,
+  }) {
+    this.endpoint = endpoint;
+    this.storageKey = storageKey;
+    this.buildPayload = buildPayload;
+    this.extractToken = extractToken;
+  }
+
+  /**
+   * @returns {Promise<object>}
+   */
+  async loadValues() {
+    const stored = await AsyncStorage.getItem(this.storageKey);
+
+    if (!stored) {
+      return {};
+    }
+
+    return JSON.parse(stored);
+  }
+
+  /**
+   * @param {object} values
+   * @returns {Promise<void>}
+   */
+  async persistValues(values) {
+    await AsyncStorage.setItem(
+      this.storageKey,
+      JSON.stringify(values)
+    );
+  }
+
+  /**
+   * @param {object} values
+   * @returns {Promise<any>}
+   */
+  async fetchResponse(values) {
+    await this.persistValues(values);
+
+    const payload = this.buildPayload
+      ? this.buildPayload(values)
+      : values;
+
+    console.log(this.endpoint);
+    console.log(payload);
+
+    const res = await fetch(this.endpoint.url, {
+      method: this.endpoint.method || 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.endpoint.headers || {}),
+      },
+      body: JSON.stringify(payload),
+    });
+
+    return await res.json();
+  }
+
+  getResponseError(response) {
+    if (!response) {
+      return undefined;
+    }
+
+    if (response.status === 'error') {
+      return response.error || response.message || 'Something went wrong.';
+    }
+
+    if (response.error) {
+      return response.error;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * @param {any} response
+   * @returns {string|undefined}
+   */
+  getToken(response) {
+    if (!response) {
+      return undefined;
+    }
+
+    if (this.extractToken) {
+      return this.extractToken(response);
+    }
+
+    return response.token;
+  }
+}

package/lib/components/gradient-tile.jsx

@@ -0,0 +1,49 @@
+// 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 { StyleSheet } from 'react-native';
+import { LinearGradient } from 'expo-linear-gradient';
+
+import TileBase from './tile-base';
+
+const defaultStyle = StyleSheet.create({
+  background: {
+    ...StyleSheet.absoluteFillObject,
+  },
+});
+
+const DEFAULT_START = { x: 0, y: 0 };
+const DEFAULT_END = { x: 1, y: 1 };
+
+/**
+ * Tile with a linear gradient background.
+ *
+ * @param {object} props
+ * @param {string[]} props.colors
+ * @param {object} [props.start]
+ * @param {object} [props.end]
+ */
+export default function GradientTile({
+  colors,
+  start = DEFAULT_START,
+  end = DEFAULT_END,
+  ...props
+}) {
+  const background = (
+    <LinearGradient
+      colors={colors}
+      start={start}
+      end={end}
+      style={defaultStyle.background}
+    />
+  );
+
+  return (
+    <TileBase
+      {...props}
+      background={background}
+    />
+  );
+}

package/lib/components/hero-screen.jsx

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// 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';
+
+const defaultStyle = StyleSheet.create({
+  headerImageWrap: {
+    width: '100%',
+    height: 220,
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+  },
+  headerImage: {
+    width: '100%',
+    height: '100%',
+  },
+  titleWrap: {
+    paddingHorizontal: 8,
+    paddingTop: 8,
+    paddingBottom: 8,
+  },
+});
+
+/**
+ * HeroScreen
+ *
+ * Thin wrapper around ParallaxScrollView that:
+ * - renders a full-bleed header image
+ * - renders optional title/header content below the image
+ * - renders children below that
+ *
+ * @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 {object} [props.containerStyle]
+ * @param {object} [props.headerStyle]
+ * @param {object} [props.contentStyle]
+ *
+ * @returns {JSX.Element}
+ */
+export default function HeroScreen({
+  children,
+  headerImage,
+  headerOverlay,
+
+  backgroundColor,
+  headerBackgroundColor,
+  headerHeight,
+
+  ContentComponent,
+  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}
+      />
+    );
+  }
+
+  return (
+    <ParallaxScrollView
+      backgroundColor={backgroundColor}
+      headerBackgroundColor={headerBackgroundColor}
+      headerHeight={headerHeight}
+      ContentComponent={ContentComponent}
+      containerStyle={containerStyle}
+      headerStyle={headerStyle}
+      contentStyle={contentStyle}
+      headerImage={
+        <View style={defaultStyle.headerImageWrap}>
+          {hi}
+        </View>
+      }
+    >
+      {headerOverlay ? (
+        <View style={defaultStyle.titleWrap}>
+          {headerOverlay}
+        </View>
+      ) : null}
+
+      {children}
+    </ParallaxScrollView>
+  );
+}
+