@myazahq/kyc-sdk-react-native 2.0.2 → 2.1.0

package/src/components/FlashOverlay.tsx

@@ -0,0 +1,156 @@
+import React, { useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { useStore } from 'zustand';
+import Svg, { Path, Rect } from 'react-native-svg';
+
+import { holePath, type FlashHole } from './flashHoleGeometry';
+import { useKycStore } from './runtime';
+import { MyazaText } from './Typography';
+import { spacing } from '../config/theme';
+
+export type { FlashHole } from './flashHoleGeometry';
+
+// ---------------------------------------------------------------------------
+// The flash overlay: a full-screen colour with a hole over the camera preview.
+//
+// The screen IS the light source. How much of it is lit is not cosmetic — it
+// decides how much light reaches the face, and therefore whether the reflection
+// is measurable at all. An overlay confined to the step's own body only lit the
+// inset sheet, leaving the rest of the display dark; that is a fraction of the
+// available light and it made flashes read as inconclusive.
+//
+// So it paints at the SHEET ROOT — over the header, the body and the footer,
+// but inside the same tree as the preview.
+//
+// Not in a modal of its own, which is the obvious way to reach the physical
+// screen edges and does not work: iOS scales a presenting sheet back when a
+// modal appears over it, and RN's `measureInWindow` reports Yoga LAYOUT
+// coordinates, which never reflect that UIKit transform. The cutout came back
+// as exactly the preview's layout size (300pt) while the preview was rendering
+// at ~232pt — off by the transform, and no re-measuring can converge on a value
+// the measurement API cannot observe.
+//
+// Painting in the same tree makes the hole and the preview scale TOGETHER, so
+// they agree by construction rather than by measurement. The cost is the strip
+// above an iOS page sheet, which stays unlit — a bounded, predictable loss,
+// where a misaligned hole is an unbounded one.
+//
+// A hole is not required for correctness: light lost through it is constant
+// across the neutral and lit windows, so it cancels in the comparison either
+// way. If measurement fails the overlay paints solid — the user loses sight of
+// their own framing for about a second, which is worth far less than failing
+// the check outright. Flutter takes the same fallback.
+// ---------------------------------------------------------------------------
+
+/**
+ * Rendered once at the sheet root.
+ *
+ * It subscribes to the paint slot ITSELF rather than taking props, so a colour
+ * change re-renders this leaf alone. Threading the colour down through the sheet
+ * would re-render the step on every flash — and the camera with it, mid-capture.
+ */
+export function FlashOverlay(): React.ReactElement | null {
+  const store = useKycStore();
+  const paint = useStore(store, (s) => s.flashPaint);
+  const [size, setSize] = useState<{ width: number; height: number } | null>(null);
+
+  if (!paint) return null;
+  const { color, hole } = paint;
+
+  return (
+    <View
+      testID="kyc.liveness.flash"
+      pointerEvents="none"
+      onLayout={(e) => {
+        const { width, height } = e.nativeEvent.layout;
+        if (size?.width !== width || size?.height !== height) setSize({ width, height });
+      }}
+      // zIndex covers iOS sibling stacking; elevation covers Android, where a
+      // sibling WITH elevation (the glass header) otherwise paints above any
+      // absolute overlay that has none.
+      style={[StyleSheet.absoluteFill, { zIndex: 100, elevation: 100 }]}
+    >
+      {color && size ? (
+        <Panels color={color} hole={hole} width={size.width} height={size.height} />
+      ) : null}
+    </View>
+  );
+}
+
+/**
+ * The colour, with a CIRCULAR bite taken out of it.
+ *
+ * Four rectangles around the preview were cheaper, but they can only ever
+ * describe a rectangle — against a circular preview that leaves the corners
+ * painted over the user's face, which is precisely the part they need to see to
+ * stay framed.
+ *
+ * A single even-odd path is the actual shape: the screen rectangle and the
+ * preview circle as two subpaths, so the circle is subtracted rather than drawn.
+ * One node, no mask, no per-frame compositing.
+ */
+function Panels({
+  color,
+  hole,
+  width,
+  height,
+}: {
+  color: string;
+  hole: FlashHole | null;
+  width: number;
+  height: number;
+}): React.ReactElement {
+  return (
+    <>
+      <Svg width={width} height={height} style={{ position: 'absolute', top: 0, left: 0 }}>
+        {hole ? (
+          <Path
+            // Screen rect, then the circle as two arcs. `evenodd` is what makes
+            // the second subpath a hole instead of a second filled shape.
+            d={holePath(width, height, hole)}
+            fill={color}
+            fillRule="evenodd"
+          />
+        ) : (
+          // Measurement failed — paint solid. The face is still lit, which is
+          // what the check needs; only the framing preview is lost.
+          <Rect x={0} y={0} width={width} height={height} fill={color} />
+        )}
+      </Svg>
+
+      <HoldStill hole={hole} width={width} height={height} />
+    </>
+  );
+}
+
+/**
+ * The one instruction shown during a flash.
+ *
+ * Anchored near the BOTTOM of the sheet, deliberately not hugging the cutout:
+ * text directly above and below the preview crowded the only part of the screen
+ * the user is meant to be looking at, and read as two competing messages.
+ *
+ * Clamped to sit below the cutout as well, so on a short screen — where the
+ * preview sits low — it moves down rather than landing on the face.
+ */
+function HoldStill({
+  hole,
+  width,
+  height,
+}: {
+  hole: FlashHole | null;
+  width: number;
+  height: number;
+}): React.ReactElement {
+  const belowHole = hole ? hole.y + hole.size + spacing.xl : 0;
+  const top = Math.min(Math.max(belowHole, height * 0.78), height - spacing.xl * 2);
+  return (
+    <View style={{ position: 'absolute', top, left: 0, width, alignItems: 'center' }}>
+      {/* Dark text: every palette colour is high-luminance, so white would be
+          unreadable on cyan and green. */}
+      <MyazaText variant="heading3" color="rgba(0,0,0,0.8)" style={{ textAlign: 'center' }}>
+        Hold still
+      </MyazaText>
+    </View>
+  );
+}

package/src/components/Icon.tsx

@@ -3,8 +3,13 @@ import Ionicons from '@expo/vector-icons/Ionicons';
 import {
   BadgeCheck,
   BookUser,
+  Building2,
+  Calendar,
   Camera,
   CameraOff,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
   Car,
   Check,
   CircleAlert,
@@ -13,19 +18,35 @@ import {
   Fingerprint,
   FileText,
   IdCard,
+  Image as ImageIcon,
   Landmark,
   Lightbulb,
   Globe,
+  Mail,
+  Maximize2,
   Lock,
+  MessageCircle,
+  MessageSquare,
   Moon,
   MoveLeft,
+  Nfc,
+  Smartphone,
   RefreshCw,
   ScanFace,
   ScanLine,
+  Search,
+  Zap,
+  ZapOff,
   ShieldCheck,
   Sun,
+  Timer,
   Upload,
   UserRound,
+  UserRoundPlus,
+  Link2,
+  Copy,
+  Share2,
+  UsersRound,
   VideoOff,
   Vote,
   X,
@@ -47,12 +68,29 @@ export type IconName =
   | 'lock'
   | 'alert'
   | 'refresh'
+  | 'maximize'
+  | 'calendar'
+  | 'image'
+  | 'chevron-left'
+  | 'chevron-right'
+  | 'chevron-down'
   // consent hero + process steps
   | 'shield'
   | 'badge-check'
+  | 'building-2'
   | 'user'
+  | 'user-plus'
+  | 'users'
   | 'scan-line'
   | 'scan-face'
+  | 'nfc'
+  | 'search'
+  | 'zap'
+  | 'link'
+  | 'copy'
+  | 'share'
+  | 'zap-off'
+  | 'timer'
   // id-type glyphs
   | 'fingerprint'
   | 'credit-card'
@@ -68,7 +106,13 @@ export type IconName =
   | 'camera-off'
   | 'video-off'
   | 'upload'
-  | 'lightbulb';
+  | 'x'
+  | 'lightbulb'
+  // contact verification (OTP channels + step footer)
+  | 'mail'
+  | 'smartphone'
+  | 'message-square'
+  | 'message-circle';
 
 // Maps each name to its Lucide component. Names mirror the Flutter SDK exactly:
 //   shieldCheck · badgeCheck · userRound · scanLine · scanFace · fingerprint ·
@@ -83,11 +127,28 @@ const ICONS: Record<IconName, LucideIcon> = {
   lock: Lock,
   alert: CircleAlert,
   refresh: RefreshCw,
+  maximize: Maximize2,
+  calendar: Calendar,
+  image: ImageIcon,
+  'chevron-left': ChevronLeft,
+  'chevron-right': ChevronRight,
+  'chevron-down': ChevronDown,
   shield: ShieldCheck,
   'badge-check': BadgeCheck,
+  'building-2': Building2,
   user: UserRound,
+  'user-plus': UserRoundPlus,
+  link: Link2,
+  copy: Copy,
+  share: Share2,
+  users: UsersRound,
   'scan-line': ScanLine,
   'scan-face': ScanFace,
+  nfc: Nfc,
+  search: Search,
+  zap: Zap,
+  'zap-off': ZapOff,
+  timer: Timer,
   fingerprint: Fingerprint,
   'credit-card': CreditCard,
   globe: Globe,
@@ -102,7 +163,12 @@ const ICONS: Record<IconName, LucideIcon> = {
   'camera-off': CameraOff,
   'video-off': VideoOff,
   upload: Upload,
+  x: X,
   lightbulb: Lightbulb,
+  mail: Mail,
+  smartphone: Smartphone,
+  'message-square': MessageSquare,
+  'message-circle': MessageCircle,
 };
 
 export interface IconProps {

package/src/components/KycFlow.tsx

@@ -2,32 +2,27 @@ import React, { useEffect, useMemo, useRef } from 'react';
 import { View } from 'react-native';
 
 import { radius, spacing } from '../config/theme';
-import { ID_TYPES, requiresDocumentCapture } from '../config/idTypes';
+import { buildStepOrder } from '../config/stepOrder';
+import { stepOrderOptions } from '../store/kycStore';
 import { KYCError } from '../types/verification';
 import { safeReportError } from '../services/errors';
 import type { KYCStep, SupportedCountry } from '../types/config';
-import { useKyc, useKycConfig, useKycStore, useTheme } from './runtime';
+import { useEffectiveCountry, useKyc, useKycConfig, useKycStore, useTheme } from './runtime';
+import { COUNTRY_SEARCH_THRESHOLD } from '../screens/CountrySelectStep';
 import { KycSheet } from './KycSheet';
+import { FatalConfigError } from './flow/FatalConfigError';
 import { ToastProvider } from './toast';
 import { MyazaText } from './Typography';
 import { MyazaButton } from './MyazaButton';
 import { Icon } from './Icon';
-import { ConsentStep } from '../screens/ConsentStep';
-import { IdTypeStep } from '../screens/IdTypeStep';
-import { IdInputStep } from '../screens/IdInputStep';
-import { DocumentCaptureStep, documentCaptureMeta } from '../screens/DocumentCaptureStep';
-import { LivenessStep } from '../screens/LivenessStep';
-import { SubmittedStep } from '../screens/SubmittedStep';
+import { StepView } from './StepView';
+import { stepHeaderMeta } from './stepHeaderMeta';
+import { countrySelectOptions } from '../store/derive';
 
 // The step router — 1:1 with the Flutter SDK's _KycFlowWidget. Computes per-step
 // header title/description, the 4-step indicator info, back/country, fetches the
 // server config on mount, and gates the flow on fatal auth failures.
 
-function labelFor(country: SupportedCountry, idType: string | null): string {
-  if (!idType) return 'Document';
-  return Object.values(ID_TYPES).flat().find((t) => t.key === idType)?.label ?? 'Document';
-}
-
 /**
  * Result of a back request handled inside the flow:
  *   'navigated' — went back a step; the caller should NOT close.
@@ -47,11 +42,14 @@ export function KycFlow({
 }): React.ReactElement {
   const { colors } = useTheme();
   const config = useKycConfig();
+  const country = useEffectiveCountry();
   const store = useKycStore();
   const currentStep = useKyc((s) => s.currentStep);
   const selectedIdType = useKyc((s) => s.selectedIdType);
   const documentCapturePhase = useKyc((s) => s.documentCapturePhase);
+  const contactChallenge = useKyc((s) => s.contactChallenge);
   const serverConfig = useKyc((s) => s.serverConfig);
+  const immersiveCapture = useKyc((s) => s.immersiveCapture);
 
   const startedRef = useRef(false);
   const reportedRef = useRef(false);
@@ -60,7 +58,11 @@ export function KycFlow({
     if (!startedRef.current) {
       startedRef.current = true;
       config.onStart?.();
-      void store.getState().loadServerConfig();
+      // A resolved workflow already delivered the allowlist + branding, so
+      // there is nothing to fetch.
+      if (store.getState().serverConfig.status !== 'ready') {
+        void store.getState().loadServerConfig();
+      }
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
@@ -75,41 +77,42 @@ export function KycFlow({
   }, [isFatal, serverConfig.statusCode, serverConfig.message, config.onError]);
 
   // ── Per-step header meta ──────────────────────────────────────────────────
-  const meta = useMemo(() => {
-    const label = labelFor(config.country, selectedIdType);
-    switch (currentStep) {
-      case 'consent':
-        return { title: '', description: null as string | null };
-      case 'id-type':
-        return { title: 'Select ID Type', description: "Choose the type of identification document you'd like to use." };
-      case 'id-input':
-        return { title: 'Enter Your Details', description: `Provide your ${label} for verification.` };
-      case 'document-capture':
-        // Phase-aware title/description live in the header (synced from the
-        // capture screen via `documentCapturePhase`) — mirrors Flutter.
-        return documentCaptureMeta(documentCapturePhase, label);
-      case 'liveness':
-        return { title: 'Face Verification', description: 'Follow the on-screen instructions' };
-      case 'submitted':
-      default:
-        return { title: '', description: null };
-    }
-  }, [currentStep, config.country, selectedIdType, documentCapturePhase]);
+  const meta = useMemo(
+    () =>
+      stepHeaderMeta(currentStep, {
+        config,
+        country,
+        selectedIdType,
+        documentCapturePhase,
+        contactChallenge,
+      }),
+    [currentStep, config, country, selectedIdType, documentCapturePhase, contactChallenge],
+  );
 
-  // ── Step indicator info (consent, id-type, capture|input, liveness?) ───────
+  // ── Step indicator info ───────────────────────────────────────────────────
+  // Read from the SAME ordered list navigation uses, so the dots can never
+  // describe a different flow than the one the user is walking. This used to be
+  // its own hand-written copy of the sequence, which meant a step added to the
+  // flow silently didn't count towards progress.
+  //
+  // 'submitted' is excluded on purpose — it is the terminal screen, not a step
+  // to make progress towards, and the indicator is hidden there.
+  //
+  // The derivation is memoised rather than done inside the selector: zustand
+  // compares snapshots by identity, so a selector that mints a fresh object on
+  // every call re-renders forever.
+  const state = useKyc((s) => s);
   const stepInfo = useMemo(() => {
-    if (currentStep === 'submitted') return null;
-    const hasCapture =
-      config.enableDocumentCapture && (selectedIdType ? requiresDocumentCapture(selectedIdType) : true);
-    const hasLiveness = config.enableLiveness !== false && config.enableSelfie !== false;
-    const steps: KYCStep[] = ['consent', 'id-type', hasCapture ? 'document-capture' : 'id-input'];
-    if (hasLiveness) steps.push('liveness');
-    const idx = steps.indexOf(currentStep);
+    if (state.currentStep === 'submitted') return null;
+    const steps = buildStepOrder(stepOrderOptions(state)).filter((s) => s !== 'submitted');
+    const idx = steps.indexOf(state.currentStep);
     if (idx < 0) return null;
     return { progress: (idx + 1) / steps.length, stepCount: steps.length };
-  }, [currentStep, config.enableDocumentCapture, config.enableLiveness, config.enableSelfie, selectedIdType]);
+  }, [state]);
 
-  const country = currentStep === 'id-type' || currentStep === 'id-input' ? config.country : null;
+  // The flag beside the title names the country whose IDs are on screen.
+  const headerCountry =
+    currentStep === 'id-type' || currentStep === 'id-input' ? country : null;
   const onBack = currentStep === 'consent' || currentStep === 'submitted' ? null : () => store.getState().previousStep();
 
   // Android hardware back arrives via the <Modal>'s onRequestClose. Expose a
@@ -136,36 +139,7 @@ export function KycFlow({
   }, [backRef, canGoBack, disableClose, store]);
 
   if (isFatal) {
-    return (
-      <KycSheet title="" onClose={onClose} hideBrand>
-        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
-          <View
-            style={{
-              width: 80,
-              height: 80,
-              borderRadius: radius.full,
-              backgroundColor: `${colors.error}1A`,
-              alignItems: 'center',
-              justifyContent: 'center',
-            }}
-          >
-            <Icon name="alert" size={40} color={colors.error} />
-          </View>
-          <View style={{ height: spacing.lg }} />
-          <MyazaText variant="heading2" style={{ textAlign: 'center' }}>
-            Unable to start verification
-          </MyazaText>
-          <View style={{ height: spacing.xs }} />
-          <MyazaText variant="bodyMedium" color={colors.textSecondary} style={{ textAlign: 'center' }}>
-            {serverConfig.message ?? 'Please check your API key and try again.'}
-          </MyazaText>
-          <View style={{ height: spacing.lg }} />
-          <View style={{ width: '100%' }}>
-            <MyazaButton label="Close" onPress={onClose} />
-          </View>
-        </View>
-      </KycSheet>
-    );
+    return <FatalConfigError message={serverConfig.message} onClose={onClose} />;
   }
 
   return (
@@ -175,31 +149,29 @@ export function KycFlow({
         description={meta.description}
         progress={stepInfo?.progress ?? null}
         stepCount={stepInfo?.stepCount ?? null}
-        country={country}
+        country={headerCountry}
         onBack={onBack}
         onClose={onClose}
+        // The searchable country picker pins its search box above a list that
+        // can run to ~240 rows. Only the multi-country variant needs it: a
+        // short flat list is happier in the normal scroll body.
+        fillsViewport={
+          currentStep === 'country-select' &&
+          countrySelectOptions({ config, serverConfig }).length > COUNTRY_SEARCH_THRESHOLD
+        }
+        // A live camera asks for the whole screen: the sheet's header, padding
+        // and scroll view are exactly what force a small viewfinder on a short
+        // phone, and a camera you have to scroll to is a broken camera.
+        //
+        // Passed as a PROP rather than rendered as its own tree. The earlier
+        // shape early-returned a different element tree, which changed the
+        // step's parent MID-STEP — React unmounted and remounted it, wiping the
+        // acknowledged primer and bouncing straight back to it. Scoped to the
+        // step as well as the flag so the next step cannot inherit it.
+        immersive={immersiveCapture && currentStep === 'document-capture'}
       >
         <StepView step={currentStep} onClose={onClose} />
       </KycSheet>
     </ToastProvider>
   );
 }
-
-function StepView({ step, onClose }: { step: KYCStep; onClose: () => void }): React.ReactElement {
-  switch (step) {
-    case 'consent':
-      return <ConsentStep />;
-    case 'id-type':
-      return <IdTypeStep />;
-    case 'id-input':
-      return <IdInputStep />;
-    case 'document-capture':
-      return <DocumentCaptureStep />;
-    case 'liveness':
-      return <LivenessStep />;
-    case 'submitted':
-      return <SubmittedStep onClose={onClose} />;
-    default:
-      return <ConsentStep />;
-  }
-}