@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/ui/overlays/AnalyzingOverlay.tsx

@@ -0,0 +1,323 @@
+/**
+ * Full-screen overlay shown after the last liveness challenge completes,
+ * while the SDK waits for SESSION_COMPLETE + /liveness-verify to resolve.
+ *
+ * Without this the camera would freeze on the last challenge's headline
+ * for several seconds while the worker drains its queue, which felt
+ * stuck. The animation here gives the user a clear "we're working on it"
+ * signal — three concentric rings pulse out from a central face/scan
+ * icon and a small dot loop trails the headline.
+ *
+ * Pure JS animations via `Animated` + react-native-svg. No Lottie / no
+ * native dependency beyond what the SDK already needs.
+ */
+
+import { useEffect, useMemo } from 'react';
+import {
+  Animated,
+  Easing,
+  StyleSheet,
+  Text,
+  useWindowDimensions,
+  View,
+} from 'react-native';
+import Svg, { Circle, Path } from 'react-native-svg';
+
+import { useTheme, withAlpha } from '../theme';
+
+export interface AnalyzingOverlayProps {
+  /** Main headline shown under the animation (e.g. "Analyzing your video"). */
+  headline: string;
+  /**
+   * Optional second-line caption (e.g. "Hang tight, this only takes a
+   * moment"). Pass `null` to omit.
+   */
+  caption?: string | null;
+}
+
+const RING_COUNT = 3;
+const RING_DURATION_MS = 1800;
+const DOT_DURATION_MS = 1200;
+
+export function AnalyzingOverlay({ headline, caption }: AnalyzingOverlayProps) {
+  const theme = useTheme();
+  const { width: screenW, height: screenH } = useWindowDimensions();
+  const ringSize = Math.min(screenW * 0.55, 260);
+  const iconSize = ringSize * 0.36;
+
+  // One Animated.Value per ring, started staggered so the pulses don't all
+  // line up. `useNativeDriver: true` keeps the animation on the UI thread
+  // even when JS is busy decoding frames / posting verify.
+  const ringAnims = useMemo(
+    () => Array.from({ length: RING_COUNT }, () => new Animated.Value(0)),
+    [],
+  );
+
+  useEffect(() => {
+    const loops = ringAnims.map((value, index) => {
+      const loop = Animated.loop(
+        Animated.sequence([
+          Animated.delay((RING_DURATION_MS / RING_COUNT) * index),
+          Animated.timing(value, {
+            toValue: 1,
+            duration: RING_DURATION_MS,
+            easing: Easing.out(Easing.cubic),
+            useNativeDriver: true,
+          }),
+          Animated.timing(value, {
+            toValue: 0,
+            duration: 0,
+            useNativeDriver: true,
+          }),
+        ]),
+      );
+      loop.start();
+      return loop;
+    });
+    return () => loops.forEach((l) => l.stop());
+  }, [ringAnims]);
+
+  // Three trailing dots cycling under the headline.
+  const dotAnims = useMemo(
+    () => Array.from({ length: 3 }, () => new Animated.Value(0)),
+    [],
+  );
+  useEffect(() => {
+    const loops = dotAnims.map((value, index) => {
+      const loop = Animated.loop(
+        Animated.sequence([
+          Animated.delay((DOT_DURATION_MS / 3) * index),
+          Animated.timing(value, {
+            toValue: 1,
+            duration: DOT_DURATION_MS / 2,
+            easing: Easing.out(Easing.quad),
+            useNativeDriver: true,
+          }),
+          Animated.timing(value, {
+            toValue: 0,
+            duration: DOT_DURATION_MS / 2,
+            easing: Easing.in(Easing.quad),
+            useNativeDriver: true,
+          }),
+        ]),
+      );
+      loop.start();
+      return loop;
+    });
+    return () => loops.forEach((l) => l.stop());
+  }, [dotAnims]);
+
+  return (
+    <View
+      style={[
+        styles.root,
+        { backgroundColor: theme.backgroundColor, minHeight: screenH },
+      ]}
+      accessible
+      accessibilityRole="alert"
+      accessibilityLiveRegion="polite"
+      accessibilityLabel={headline}
+    >
+      <View
+        style={[styles.stage, { width: ringSize, height: ringSize }]}
+        pointerEvents="none"
+      >
+        {ringAnims.map((value, i) => (
+          <Animated.View
+            key={i}
+            style={[
+              styles.ring,
+              {
+                width: ringSize,
+                height: ringSize,
+                borderRadius: ringSize / 2,
+                borderColor: theme.primaryColor,
+                transform: [
+                  {
+                    scale: value.interpolate({
+                      inputRange: [0, 1],
+                      outputRange: [0.55, 1],
+                    }),
+                  },
+                ],
+                opacity: value.interpolate({
+                  inputRange: [0, 0.15, 1],
+                  outputRange: [0, 0.55, 0],
+                }),
+              },
+            ]}
+          />
+        ))}
+        <View
+          style={[
+            styles.iconBubble,
+            {
+              width: iconSize * 1.55,
+              height: iconSize * 1.55,
+              borderRadius: (iconSize * 1.55) / 2,
+              backgroundColor: withAlpha(theme.primaryColor, 0.12),
+            },
+          ]}
+        >
+          <FaceScanIcon size={iconSize} color={theme.primaryColor} />
+        </View>
+      </View>
+
+      <View style={styles.copy}>
+        <View style={styles.headlineRow}>
+          <Text
+            style={[styles.headline, { color: theme.textColor }]}
+            numberOfLines={2}
+          >
+            {headline}
+          </Text>
+          <View style={styles.dots}>
+            {dotAnims.map((value, i) => (
+              <Animated.View
+                key={i}
+                style={[
+                  styles.dot,
+                  {
+                    backgroundColor: theme.textColor,
+                    opacity: value.interpolate({
+                      inputRange: [0, 1],
+                      outputRange: [0.2, 1],
+                    }),
+                    transform: [
+                      {
+                        translateY: value.interpolate({
+                          inputRange: [0, 1],
+                          outputRange: [0, -3],
+                        }),
+                      },
+                    ],
+                  },
+                ]}
+              />
+            ))}
+          </View>
+        </View>
+        {caption ? (
+          <Text
+            style={[styles.caption, { color: theme.textSecondaryColor }]}
+            numberOfLines={3}
+          >
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+/**
+ * Schematic face inside a viewfinder bracket. Reads as "we're scanning
+ * the captured face" without depending on @expo/vector-icons (which is
+ * optional in the SDK's dependency tree).
+ */
+function FaceScanIcon({ size, color }: { size: number; color: string }) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 48 48">
+      {/* Viewfinder corner brackets */}
+      <Path
+        d="M6 14 V8 H14"
+        stroke={color}
+        strokeWidth={2.5}
+        strokeLinecap="round"
+        fill="none"
+      />
+      <Path
+        d="M42 14 V8 H34"
+        stroke={color}
+        strokeWidth={2.5}
+        strokeLinecap="round"
+        fill="none"
+      />
+      <Path
+        d="M6 34 V40 H14"
+        stroke={color}
+        strokeWidth={2.5}
+        strokeLinecap="round"
+        fill="none"
+      />
+      <Path
+        d="M42 34 V40 H34"
+        stroke={color}
+        strokeWidth={2.5}
+        strokeLinecap="round"
+        fill="none"
+      />
+      {/* Face oval */}
+      <Path
+        d="M24 16 C 30 16 33 20 33 26 C 33 31 29 35 24 35 C 19 35 15 31 15 26 C 15 20 18 16 24 16 Z"
+        stroke={color}
+        strokeWidth={2}
+        fill="none"
+      />
+      {/* Eyes */}
+      <Circle cx={20} cy={24} r={1.4} fill={color} />
+      <Circle cx={28} cy={24} r={1.4} fill={color} />
+      {/* Smile */}
+      <Path
+        d="M20 29 C 22 31 26 31 28 29"
+        stroke={color}
+        strokeWidth={1.8}
+        strokeLinecap="round"
+        fill="none"
+      />
+    </Svg>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 32,
+    gap: 32,
+  },
+  stage: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    position: 'relative',
+  },
+  ring: {
+    position: 'absolute',
+    borderWidth: 2,
+  },
+  iconBubble: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  copy: {
+    alignItems: 'center',
+    gap: 8,
+    maxWidth: 360,
+  },
+  headlineRow: {
+    flexDirection: 'row',
+    alignItems: 'flex-end',
+    gap: 6,
+  },
+  headline: {
+    fontSize: 18,
+    fontWeight: '600',
+    textAlign: 'center',
+  },
+  dots: {
+    flexDirection: 'row',
+    gap: 3,
+    paddingBottom: 6,
+  },
+  dot: {
+    width: 4,
+    height: 4,
+    borderRadius: 2,
+  },
+  caption: {
+    fontSize: 14,
+    textAlign: 'center',
+    lineHeight: 20,
+  },
+});

package/src/ui/overlays/LoadingOverlay.tsx

@@ -0,0 +1,115 @@
+/**
+ * Full-bleed loading overlay.
+ *
+ * Visual rules (per UI/UX Pro Max guidance):
+ *   - Solid surface, no halo / radial gradient that "ghosts" the underlying
+ *     UI. Surfaces must read as a clean replacement, not a translucent veil.
+ *   - Spinner is a thin ring with one tinted segment that rotates — the
+ *     classic indeterminate progress affordance. Single visual element on
+ *     screen, motion expresses ongoing work (animation §motion-meaning).
+ *   - Honors `useReducedMotion()` (animation §reduced-motion). When motion
+ *     is reduced, the ring stays static and the message stays visible.
+ *   - Token-driven colors only — primary for the active segment, border
+ *     color for the track. No raw hex inside the component.
+ */
+
+import { useEffect, useRef } from 'react';
+import { Animated, Easing, StyleSheet, Text, View } from 'react-native';
+import { useReducedMotion, useTheme } from '../theme';
+
+export interface LoadingOverlayProps {
+  message?: string | null;
+}
+
+const RING_SIZE = 56;
+const RING_THICKNESS = 4;
+
+export function LoadingOverlay({ message }: LoadingOverlayProps) {
+  const theme = useTheme();
+  const reduceMotion = useReducedMotion();
+  const trimmed = (message ?? '').trim();
+  const isAnimationOnly = trimmed.length === 0;
+
+  const rotation = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (reduceMotion) {
+      rotation.setValue(0);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.timing(rotation, {
+        toValue: 1,
+        duration: 900,
+        easing: Easing.linear,
+        useNativeDriver: true,
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [reduceMotion, rotation]);
+
+  const spin = rotation.interpolate({
+    inputRange: [0, 1],
+    outputRange: ['0deg', '360deg'],
+  });
+
+  return (
+    <View
+      accessibilityRole="progressbar"
+      accessibilityLiveRegion="polite"
+      accessibilityLabel={isAnimationOnly ? 'Loading' : trimmed}
+      style={[
+        styles.root,
+        { backgroundColor: theme.backgroundColor },
+      ]}
+      pointerEvents="auto"
+    >
+      <View style={styles.content}>
+        <Animated.View
+          style={[
+            styles.ring,
+            {
+              borderColor: theme.borderColor,
+              borderTopColor: theme.primaryColor,
+              transform: [{ rotate: spin }],
+            },
+          ]}
+        />
+        {!isAnimationOnly ? (
+          <Text style={[styles.text, { color: theme.textColor }]}>
+            {trimmed}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 32,
+    zIndex: 1000,
+  },
+  content: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  ring: {
+    width: RING_SIZE,
+    height: RING_SIZE,
+    borderRadius: RING_SIZE / 2,
+    borderWidth: RING_THICKNESS,
+  },
+  text: {
+    fontSize: 15,
+    fontWeight: '500',
+    textAlign: 'center',
+    maxWidth: 320,
+    lineHeight: 22,
+    marginTop: 18,
+  },
+});

package/src/ui/overlays/ProgressBar.tsx

@@ -0,0 +1,99 @@
+/**
+ * Top-of-screen progress bar. Trickling model:
+ *   - `tick()` advances 12% per step, soft-cap at 90%.
+ *   - `complete()` jumps to 100% and fades out.
+ *
+ * Animated with `Animated.timing` (driver: native) so we don't pull in
+ * Reanimated yet; respects `useReducedMotion()`.
+ */
+
+import { useEffect, useRef } from 'react';
+import { Animated, StyleSheet } from 'react-native';
+import { mixHex, useReducedMotion, useTheme } from '../theme';
+
+export interface ProgressBarProps {
+  /** 0–100. Components compute the trickling logic externally and pass it in. */
+  value: number;
+  /** When true, the bar fades out (used after `complete()`). */
+  hidden?: boolean;
+}
+
+export function ProgressBar({ value, hidden = false }: ProgressBarProps) {
+  const theme = useTheme();
+  const reduceMotion = useReducedMotion();
+  const widthAnim = useRef(new Animated.Value(value)).current;
+  const opacityAnim = useRef(new Animated.Value(hidden ? 0 : 1)).current;
+
+  useEffect(() => {
+    Animated.timing(widthAnim, {
+      toValue: value,
+      duration: reduceMotion ? 0 : 360,
+      useNativeDriver: false,
+    }).start();
+  }, [value, reduceMotion, widthAnim]);
+
+  useEffect(() => {
+    Animated.timing(opacityAnim, {
+      toValue: hidden ? 0 : 1,
+      duration: reduceMotion ? 0 : 240,
+      useNativeDriver: true,
+    }).start();
+  }, [hidden, reduceMotion, opacityAnim]);
+
+  const trackColor = mixHex(theme.borderColor, theme.backgroundColor, 50);
+
+  return (
+    <Animated.View
+      accessibilityRole="progressbar"
+      accessibilityValue={{ now: Math.round(value), min: 0, max: 100 }}
+      style={[
+        styles.track,
+        { backgroundColor: trackColor, opacity: opacityAnim },
+      ]}
+    >
+      <Animated.View
+        style={[
+          styles.bar,
+          {
+            backgroundColor: theme.primaryColor,
+            width: widthAnim.interpolate({
+              inputRange: [0, 100],
+              outputRange: ['0%', '100%'],
+            }),
+          },
+        ]}
+      />
+    </Animated.View>
+  );
+}
+
+const STEP_INCREMENT_PCT = 12;
+const SOFT_CAP_PCT = 90;
+
+/**
+ * Helper that encapsulates the trickling logic. Exposed so step modules /
+ * the orchestrator hold the value in plain state and pass it down to
+ * `<ProgressBar value={...} />`.
+ */
+export const PROGRESS_BAR = {
+  tick(current: number): number {
+    return Math.min(SOFT_CAP_PCT, current + STEP_INCREMENT_PCT);
+  },
+  complete(): number {
+    return 100;
+  },
+  reset(): number {
+    return 0;
+  },
+};
+
+const styles = StyleSheet.create({
+  track: {
+    height: 4,
+    width: '100%',
+    overflow: 'hidden',
+  },
+  bar: {
+    height: '100%',
+  },
+});

package/src/ui/overlays/RetryDialog.tsx

@@ -0,0 +1,128 @@
+/**
+ * In-flow recoverable error dialog. Solid backdrop (no transparency), warning
+ * accent, "Try again / Cancel" buttons, primary focus on retry.
+ *
+ * Used by every step module's POST catch handler — gives the user a chance to
+ * recover without losing their inputs.
+ */
+
+import { StyleSheet, Text, View } from 'react-native';
+import { Button } from '../primitives/Button';
+import { mixHex, useTheme, withAlpha } from '../theme';
+
+export interface RetryDialogProps {
+  title: string;
+  message: string;
+  retryLabel: string;
+  cancelLabel: string;
+  onRetry: () => void;
+  onCancel: () => void;
+}
+
+export function RetryDialog({
+  title,
+  message,
+  retryLabel,
+  cancelLabel,
+  onRetry,
+  onCancel,
+}: RetryDialogProps) {
+  const theme = useTheme();
+
+  return (
+    <View
+      accessibilityViewIsModal
+      accessibilityRole="alert"
+      accessibilityLiveRegion="assertive"
+      style={[
+        styles.root,
+        { backgroundColor: theme.backgroundColor },
+      ]}
+    >
+      <View style={styles.card}>
+        <View
+          style={[
+            styles.iconWrap,
+            {
+              backgroundColor: mixHex(theme.warningColor, theme.backgroundColor, 16),
+              borderColor: withAlpha(theme.warningColor, 0.35),
+            },
+          ]}
+        >
+          <Text style={[styles.iconText, { color: theme.warningColor }]}>!</Text>
+        </View>
+        <Text style={[styles.title, { color: theme.textColor }]}>{title}</Text>
+        <Text
+          style={[styles.body, { color: theme.textSecondaryColor }]}
+          numberOfLines={6}
+        >
+          {message}
+        </Text>
+        <View style={styles.actions}>
+          <Button
+            variant="ghost"
+            label={cancelLabel}
+            onPress={onCancel}
+            fullWidth={false}
+            style={styles.btn}
+          />
+          <Button
+            variant="primary"
+            label={retryLabel}
+            onPress={onRetry}
+            fullWidth={false}
+            style={styles.btn}
+          />
+        </View>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+    zIndex: 1100,
+  },
+  card: {
+    width: '100%',
+    maxWidth: 420,
+    alignItems: 'center',
+    gap: 14,
+  },
+  iconWrap: {
+    width: 64,
+    height: 64,
+    borderRadius: 32,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderWidth: 1,
+  },
+  iconText: {
+    fontSize: 28,
+    fontWeight: '800',
+    lineHeight: 32,
+  },
+  title: {
+    fontSize: 17,
+    fontWeight: '700',
+    textAlign: 'center',
+  },
+  body: {
+    fontSize: 14,
+    lineHeight: 20,
+    textAlign: 'center',
+  },
+  actions: {
+    flexDirection: 'row',
+    gap: 10,
+    marginTop: 6,
+    alignSelf: 'stretch',
+  },
+  btn: {
+    flex: 1,
+  },
+});

package/src/ui/overlays/index.ts

@@ -0,0 +1,3 @@
+export { LoadingOverlay, type LoadingOverlayProps } from './LoadingOverlay';
+export { RetryDialog, type RetryDialogProps } from './RetryDialog';
+export { ProgressBar, PROGRESS_BAR, type ProgressBarProps } from './ProgressBar';