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

package/src/ui/MapFallbackBoundary.tsx

@@ -0,0 +1,46 @@
+/**
+ * Error boundary that catches render failures from `react-native-maps` and
+ * lets the parent fall back to the manual address form.
+ *
+ * Specifically the `AirGoogleMaps` runtime error (`AirGoogleMaps dir must be
+ * added to your xCode project to support GoogleMaps on iOS`) only surfaces
+ * when the MapView mounts. The preflight check cannot detect it because the
+ * native module exists — it's just missing its iOS sub-target.
+ */
+
+import { Component, type ReactNode } from 'react';
+import { log } from '../utils/log';
+
+interface Props {
+  children: ReactNode;
+  /** Called once when the boundary catches an error from any descendant. */
+  onError: (error: Error) => void;
+  /** Rendered while the boundary is in the errored state, before the parent reacts. */
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+}
+
+export class MapFallbackBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error): void {
+    log.warn('[MapFallbackBoundary] map render failed, switching to manual', {
+      message: error.message,
+    });
+    this.props.onError(error);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? null;
+    }
+    return this.props.children;
+  }
+}

package/src/ui/StepShell.tsx

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Step shell — header + scrollable body.
+ *
+ * Rounded header icon, title, subtitle, then a centered column with the
+ * step's form. Used by every form-style step (HUMAN_BASIC_INFO, TAX_INFO, …)
+ * so they read as a single visual family.
+ */
+
+import type { ReactNode } from 'react';
+import {
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
+import { useTheme, withAlpha } from './theme';
+
+export interface StepShellProps {
+  title: string;
+  subtitle?: string | undefined;
+  /** Optional icon-bearing element (e.g. SVG). Falls back to a colored disc. */
+  iconNode?: ReactNode | undefined;
+  children: ReactNode;
+  /** When true, the body is wrapped in a `KeyboardAvoidingView` (form-friendly). */
+  avoidKeyboard?: boolean | undefined;
+}
+
+export function StepShell({
+  title,
+  subtitle,
+  iconNode,
+  children,
+  avoidKeyboard = true,
+}: StepShellProps) {
+  const theme = useTheme();
+
+  const showIconCircle = !theme.hideStepIcons && iconNode != null;
+
+  const body = (
+    <ScrollView
+      style={styles.scroll}
+      contentContainerStyle={styles.scrollBody}
+      keyboardShouldPersistTaps="handled"
+    >
+      <View style={styles.header}>
+        {showIconCircle ? (
+          <View
+            style={[
+              styles.iconCircle,
+              {
+                backgroundColor: theme.primaryColor,
+                shadowColor: withAlpha(theme.primaryColor, 0.5),
+              },
+            ]}
+            accessibilityElementsHidden
+            importantForAccessibility="no"
+          >
+            {iconNode}
+          </View>
+        ) : null}
+        <Text style={[styles.title, { color: theme.textColor }]}>{title}</Text>
+        {subtitle ? (
+          <Text
+            style={[styles.subtitle, { color: theme.textSecondaryColor }]}
+          >
+            {subtitle}
+          </Text>
+        ) : null}
+      </View>
+      <View style={styles.column}>{children}</View>
+    </ScrollView>
+  );
+
+  if (avoidKeyboard) {
+    return (
+      <KeyboardAvoidingView
+        style={styles.flex}
+        behavior={Platform.OS === 'ios' ? 'padding' : undefined}
+      >
+        {body}
+      </KeyboardAvoidingView>
+    );
+  }
+  return body;
+}
+
+const styles = StyleSheet.create({
+  flex: {
+    flex: 1,
+  },
+  scroll: {
+    flex: 1,
+  },
+  scrollBody: {
+    paddingHorizontal: 18,
+    paddingTop: 12,
+    paddingBottom: 28,
+  },
+  header: {
+    alignItems: 'center',
+    marginBottom: 14,
+  },
+  iconCircle: {
+    width: 56,
+    height: 56,
+    borderRadius: 28,
+    marginBottom: 10,
+    alignItems: 'center',
+    justifyContent: 'center',
+    shadowOpacity: 0.25,
+    shadowRadius: 8,
+    shadowOffset: { width: 0, height: 3 },
+    elevation: 3,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: '700',
+    letterSpacing: -0.3,
+    textAlign: 'center',
+  },
+  subtitle: {
+    marginTop: 6,
+    fontSize: 14,
+    fontWeight: '400',
+    textAlign: 'center',
+    lineHeight: 20,
+    maxWidth: 320,
+  },
+  column: {
+    width: '100%',
+    maxWidth: 360,
+    alignSelf: 'center',
+    gap: 10,
+  },
+});

package/src/ui/VelionOnboardingScreen.tsx

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview Top-level React component the host app mounts.
+ *
+ * Owns the `VelionOnboarding` instance lifecycle, mounts the `ThemeProvider`,
+ * and renders the orchestrator's view bridge: a sticky `ProgressBar`, the
+ * active step's React node, and (when a step is between transitions or the
+ * flow finishes) a themed `LoadingOverlay` / final-result message.
+ */
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+import { VelionOnboarding, type VelionConfig } from '../core/VelionOnboarding';
+import type { OnboardingResult, OnboardingStep, SdkError } from '../types';
+import { ThemeProvider, useTheme } from './theme';
+import { LoadingOverlay } from './overlays/LoadingOverlay';
+import { PROGRESS_BAR, ProgressBar } from './overlays/ProgressBar';
+import { getStrings } from '../i18n';
+import {
+  activateScreenKeepAwake,
+  deactivateScreenKeepAwake,
+} from '../utils/keepAwake';
+
+export interface VelionOnboardingScreenProps {
+  config: VelionConfig;
+  onComplete?: ((result: OnboardingResult) => void) | undefined;
+  onFail?: ((err: SdkError) => void) | undefined;
+}
+
+interface ViewState {
+  loading: string | null;
+  stepNode: ReactNode | null;
+  error: SdkError | null;
+  result: OnboardingResult | null;
+}
+
+const INITIAL_STATE: ViewState = {
+  loading: null,
+  stepNode: null,
+  error: null,
+  result: null,
+};
+
+export function VelionOnboardingScreen({
+  config,
+  onComplete,
+  onFail,
+}: VelionOnboardingScreenProps) {
+  return (
+    <ThemeProvider
+      themeOverrides={config.theme}
+      colorMode={config.colorMode ?? 'auto'}
+    >
+      <VelionOnboardingInner
+        config={config}
+        onComplete={onComplete}
+        onFail={onFail}
+      />
+    </ThemeProvider>
+  );
+}
+
+function VelionOnboardingInner({
+  config,
+  onComplete,
+  onFail,
+}: VelionOnboardingScreenProps) {
+  const theme = useTheme();
+  const t = getStrings(config.locale);
+  const [state, setState] = useState<ViewState>(INITIAL_STATE);
+  const [progress, setProgress] = useState(0);
+  const [progressHidden, setProgressHidden] = useState(false);
+
+  const sdk = useMemo(
+    () => new VelionOnboarding(config),
+    // Recreate the SDK only when the session changes — host must keep
+    // callbacks stable (or wrap them in refs).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [config.sessionId, config.apiUrl],
+  );
+  const sdkRef = useRef(sdk);
+  sdkRef.current = sdk;
+
+  const onCompleteRef = useRef(onComplete);
+  const onFailRef = useRef(onFail);
+  onCompleteRef.current = onComplete;
+  onFailRef.current = onFail;
+
+  useEffect(() => {
+    // Hold a wake lock for the full duration of the flow. Camera-heavy steps
+    // (LIVENESS_MATCH, DOCUMENTS_OCR) involve the user holding still, so the
+    // OS screen-timeout would otherwise dim and lock the device mid-session.
+    activateScreenKeepAwake();
+
+    sdk.attachView({
+      setLoading: (text) => setState((s) => ({ ...s, loading: text })),
+      setStepNode: (node) => setState((s) => ({ ...s, stepNode: node })),
+      setError: (err) => {
+        setState((s) => ({ ...s, error: err, loading: null, stepNode: null }));
+        setProgressHidden(true);
+        onFailRef.current?.(err);
+      },
+      setResult: (result) => {
+        setState((s) => ({ ...s, result, loading: null, stepNode: null }));
+        setProgress(PROGRESS_BAR.complete());
+        // Fade after a small delay so the "100%" jump is visible.
+        setTimeout(() => setProgressHidden(true), 400);
+        onCompleteRef.current?.(result);
+      },
+    });
+
+    const unsubStepChange = sdk.on('step:change', () => {
+      setProgress((curr) => PROGRESS_BAR.tick(curr));
+    });
+
+    void sdk.start();
+
+    return () => {
+      unsubStepChange();
+      sdk.detachView();
+      sdk.destroy();
+      deactivateScreenKeepAwake();
+    };
+  }, [sdk]);
+
+  const renderBody = useCallback((): ReactNode => {
+    if (state.error) {
+      return (
+        <View style={styles.message}>
+          <Text style={[styles.title, { color: theme.errorColor }]}>
+            {state.error.declineTitle ?? t.result.declineHeadline}
+          </Text>
+          <Text style={[styles.body, { color: theme.textColor }]}>
+            {state.error.declineMessage ?? state.error.message}
+          </Text>
+        </View>
+      );
+    }
+    if (state.result) {
+      const status = state.result.status;
+      let title = t.result.approvedTitle;
+      let body = t.result.approvedBody;
+      if (status === 'MANUAL_REVIEW') {
+        title = t.result.manualReviewTitle;
+        body = t.result.manualReviewBody;
+      } else if (status === 'REJECTED' || status === 'DECLINED') {
+        title = t.result.rejectedTitle;
+        body = t.result.rejectedBody;
+      }
+      return (
+        <View style={styles.message}>
+          <Text style={[styles.title, { color: theme.textColor }]}>{title}</Text>
+          <Text style={[styles.body, { color: theme.textSecondaryColor }]}>
+            {body}
+          </Text>
+        </View>
+      );
+    }
+    if (state.stepNode) {
+      return state.stepNode;
+    }
+    return null;
+  }, [state, theme, t]);
+
+  const showLoadingOverlay =
+    !state.error && !state.result && !state.stepNode;
+  const loadingText = state.loading ?? t.common.loading;
+  // Progress bar is shown unless EITHER `config.showProgressBar === false`
+  // OR `theme.hideProgressBar === true`. Both paths exist for parity with
+  // `hideStepIcons` (theme-side) and for hosts that already wire the
+  // legacy `showProgressBar` flag (config-side).
+  const showProgress =
+    config.showProgressBar !== false && !theme.hideProgressBar;
+
+  return (
+    <View style={[styles.root, { backgroundColor: theme.backgroundColor }]}>
+      {showProgress ? (
+        <ProgressBar value={progress} hidden={progressHidden} />
+      ) : null}
+      <View style={styles.content}>{renderBody()}</View>
+      {showLoadingOverlay ? <LoadingOverlay message={loadingText} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+    overflow: 'hidden',
+  },
+  message: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 24,
+    gap: 12,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: '600',
+    textAlign: 'center',
+  },
+  body: {
+    fontSize: 15,
+    lineHeight: 22,
+    textAlign: 'center',
+    maxWidth: 360,
+  },
+});
+
+// Type tag used so consumers can identify the step that triggered an event.
+// Currently unused but kept here so future adapters (e.g. analytics wrappers)
+// can hook into orchestrator events without re-exporting types.
+export type { OnboardingStep };

package/src/ui/forms/index.ts

@@ -0,0 +1,12 @@
+export {
+  useInlineValidation,
+  type FieldRule,
+  type InlineValidationHandle,
+} from './useInlineValidation';
+export {
+  required,
+  minLength,
+  pattern,
+  compose,
+  type FieldValidator,
+} from './validators';

package/src/ui/forms/useInlineValidation.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Inline form validation hook.
+ *
+ * Implements the on-blur validation heuristic from Material Design's
+ * `inline-validation` guidelines — error appears on blur (not keystroke),
+ * clears optimistically when the user resumes typing, and re-evaluates on
+ * the next blur. The form's submit handler can call `validateAll()` to gate.
+ *
+ * Returns plain handlers + an errors map that step modules feed into
+ * `<Input errorMessage={…} />` props.
+ */
+
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type { FieldValidator } from './validators';
+
+export interface FieldRule<TFieldName extends string> {
+  name: TFieldName;
+  validate: FieldValidator;
+}
+
+export interface InlineValidationHandle<TFieldName extends string> {
+  errors: Partial<Record<TFieldName, string>>;
+  /** Bind these props to your `<Input>` to wire validation. */
+  bind: (
+    name: TFieldName,
+    value: string,
+  ) => {
+    onBlur: () => void;
+    onChangeText: (text: string) => void;
+    errorMessage: string | null;
+  };
+  validateAll: (values: Record<TFieldName, string>) => boolean;
+  reset: () => void;
+  setFieldError: (name: TFieldName, message: string | null) => void;
+}
+
+export function useInlineValidation<TFieldName extends string>(
+  rules: ReadonlyArray<FieldRule<TFieldName>>,
+  onChange?: (name: TFieldName, value: string) => void,
+): InlineValidationHandle<TFieldName> {
+  const [errors, setErrors] = useState<Partial<Record<TFieldName, string>>>({});
+  const rulesRef = useRef(rules);
+  rulesRef.current = rules;
+
+  const validateOne = useCallback(
+    (name: TFieldName, value: string): string | null => {
+      const rule = rulesRef.current.find((r) => r.name === name);
+      if (!rule) return null;
+      return rule.validate(value);
+    },
+    [],
+  );
+
+  const setFieldError = useCallback(
+    (name: TFieldName, message: string | null) => {
+      setErrors((prev) => {
+        if (message) {
+          if (prev[name] === message) return prev;
+          return { ...prev, [name]: message };
+        }
+        if (!(name in prev)) return prev;
+        const next = { ...prev };
+        delete next[name];
+        return next;
+      });
+    },
+    [],
+  );
+
+  const bind = useCallback(
+    (name: TFieldName, value: string) => ({
+      onBlur: () => {
+        const message = validateOne(name, value);
+        setFieldError(name, message);
+      },
+      onChangeText: (text: string) => {
+        onChange?.(name, text);
+        // Optimistic clear while editing — equivalent to the input listener
+        // in the web inlineValidation helper.
+        setErrors((prev) => {
+          if (!(name in prev)) return prev;
+          const next = { ...prev };
+          delete next[name];
+          return next;
+        });
+      },
+      errorMessage: errors[name] ?? null,
+    }),
+    [errors, onChange, setFieldError, validateOne],
+  );
+
+  const validateAll = useCallback(
+    (values: Record<TFieldName, string>): boolean => {
+      const next: Partial<Record<TFieldName, string>> = {};
+      let allOk = true;
+      for (const rule of rulesRef.current) {
+        const message = rule.validate(values[rule.name] ?? '');
+        if (message) {
+          next[rule.name] = message;
+          allOk = false;
+        }
+      }
+      setErrors(next);
+      return allOk;
+    },
+    [],
+  );
+
+  const reset = useCallback(() => setErrors({}), []);
+
+  return useMemo(
+    () => ({ errors, bind, validateAll, reset, setFieldError }),
+    [errors, bind, validateAll, reset, setFieldError],
+  );
+}

package/src/ui/forms/validators.ts

@@ -0,0 +1,29 @@
+/**
+ * Reusable field validators. Each validator returns either an error message or
+ * `null` when valid — same contract as `InlineFieldRule.validate` in the web
+ * SDK so step authors can move logic between platforms with minimal churn.
+ */
+
+export type FieldValidator = (value: string) => string | null;
+
+export function required(message: string): FieldValidator {
+  return (value) => (value.trim().length > 0 ? null : message);
+}
+
+export function minLength(min: number, message: string): FieldValidator {
+  return (value) => (value.trim().length >= min ? null : message);
+}
+
+export function pattern(regex: RegExp, message: string): FieldValidator {
+  return (value) => (regex.test(value) ? null : message);
+}
+
+export function compose(...validators: FieldValidator[]): FieldValidator {
+  return (value) => {
+    for (const v of validators) {
+      const msg = v(value);
+      if (msg) return msg;
+    }
+    return null;
+  };
+}

package/src/ui/icons/HomeHeartIcon.tsx

@@ -0,0 +1,34 @@
+/**
+ * Custom "home with heart" step icon for the ADDRESS_INFO step.
+ *
+ * Drawn inline with react-native-svg (already in deps for the liveness oval)
+ * so we don't depend on MaterialIcons having an exact match — none of the
+ * Material set bundles a house with a heart inside.
+ */
+
+import Svg, { Path } from 'react-native-svg';
+
+interface HomeHeartIconProps {
+  size?: number;
+  color?: string;
+}
+
+export function HomeHeartIcon({ size = 28, color = '#FFFFFF' }: HomeHeartIconProps) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24">
+      {/* House silhouette (outline) */}
+      <Path
+        d="M3 11.5 L12 3.5 L21 11.5 L21 20.5 A1.5 1.5 0 0 1 19.5 22 L4.5 22 A1.5 1.5 0 0 1 3 20.5 Z"
+        fill="none"
+        stroke={color}
+        strokeWidth={1.7}
+        strokeLinejoin="round"
+      />
+      {/* Heart inside */}
+      <Path
+        d="M12 18.2 C 9.4 16.3 7.7 14.7 7.7 13.0 C 7.7 11.7 8.7 10.7 9.9 10.7 C 10.7 10.7 11.5 11.1 12 11.8 C 12.5 11.1 13.3 10.7 14.1 10.7 C 15.3 10.7 16.3 11.7 16.3 13.0 C 16.3 14.7 14.6 16.3 12 18.2 Z"
+        fill={color}
+      />
+    </Svg>
+  );
+}

package/src/ui/icons/StepIcon.tsx

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview StepIcon — small wrapper around `MaterialIcons` (shipped with
+ * `@expo/vector-icons`, which Expo SDK 54 includes by default).
+ *
+ * Steps pass an icon by name (e.g. `<StepIcon name="badge" />`) and the
+ * shell renders it inside the colored circle next to the title. When the
+ * library can't be loaded (bare-RN host without `@expo/vector-icons`
+ * installed) we fall back silently to `null` so the circle is empty rather
+ * than crashing — the host can switch off the circle altogether via
+ * `VelionTheme.hideStepIcons`.
+ */
+
+import type { ReactElement } from 'react';
+import { Text } from 'react-native';
+import { log } from '../../utils/log';
+
+export type MaterialIconName =
+  | 'badge'
+  | 'business'
+  | 'business-center'
+  | 'gavel'
+  | 'description'
+  | 'receipt-long'
+  | 'person'
+  | 'home'
+  | 'mail-outline'
+  | 'phone-iphone'
+  | 'face'
+  | 'photo-camera'
+  | 'fingerprint';
+
+let MaterialIcons:
+  | (new () => unknown)
+  | ((props: {
+      name: string;
+      size?: number;
+      color?: string;
+    }) => unknown)
+  | null = null;
+
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+  const mod = require('@expo/vector-icons');
+  MaterialIcons = mod.MaterialIcons ?? null;
+} catch {
+  log.warn(
+    '[StepIcon] @expo/vector-icons is not installed — step header icons will be hidden. ' +
+      'Either install it (Expo SDK 54+ ships it by default) or set VelionTheme.hideStepIcons=true.',
+  );
+}
+
+export interface StepIconProps {
+  name: MaterialIconName;
+  /** Defaults to 28 px to match the circle the shell renders. */
+  size?: number;
+  /** Defaults to white (the circle is filled with `primaryColor`). */
+  color?: string;
+}
+
+/**
+ * Renders a Material icon centered inside the step's title circle. Returns
+ * `null` when `@expo/vector-icons` is unavailable so the SDK still mounts
+ * gracefully on hosts without it.
+ */
+export function StepIcon({ name, size = 28, color = '#FFFFFF' }: StepIconProps) {
+  if (!MaterialIcons) {
+    // Plain text fallback — keeps the circle from being blank when the
+    // library is missing. Picks a neutral character; not localized.
+    return <Text style={{ color, fontSize: size, fontWeight: '700' }}>•</Text>;
+  }
+  const Icon = MaterialIcons as unknown as (props: {
+    name: string;
+    size: number;
+    color: string;
+  }) => ReactElement;
+  return <Icon name={name} size={size} color={color} />;
+}