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

package/src/components/viewfinder/ImmersiveControls.tsx

@@ -0,0 +1,127 @@
+import React from 'react';
+import { ActivityIndicator, Pressable, View } from 'react-native';
+import Svg, { Circle } from 'react-native-svg';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../runtime';
+import { MyazaText } from '../Typography';
+import { Icon } from '../Icon';
+import { CountryFlag } from '../CountryFlag';
+
+// ---------------------------------------------------------------------------
+// Immersive capture chrome — 1:1 with the Flutter SDK's full-screen camera.
+//
+// Positions are deliberate and differ from the framed viewfinder:
+//   • the HINT sits at the BOTTOM, near the shutter the user is about to press,
+//     not at the top where it competes with the document itself;
+//   • the TORCH is bottom-right, in thumb reach on a phone held two-handed;
+//   • the side badge and document pill sit top, out of the frame's way.
+// ---------------------------------------------------------------------------
+
+const SCRIM = 'rgba(0,0,0,0.55)';
+
+/** Round translucent control — back, torch. */
+export function RoundControl({
+  icon,
+  label,
+  onPress,
+  active,
+  size = 48,
+  style,
+}: {
+  icon: 'back' | 'lightbulb';
+  label: string;
+  onPress: () => void;
+  active?: boolean;
+  size?: number;
+  style: object;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      style={{
+        position: 'absolute',
+        width: size,
+        height: size,
+        borderRadius: radius.full,
+        backgroundColor: active ? colors.primary : SCRIM,
+        alignItems: 'center',
+        justifyContent: 'center',
+        ...style,
+      }}
+    >
+      <Icon name={icon} size={20} color="#FFFFFF" />
+    </Pressable>
+  );
+}
+
+/** "FRONT" / "BACK" — which face of the document is expected right now. */
+export function SideBadge({ side, top }: { side: 'front' | 'back'; top: number }): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        position: 'absolute',
+        top,
+        right: spacing.md,
+        backgroundColor: colors.primary,
+        borderRadius: radius.full,
+        paddingHorizontal: 16,
+        paddingVertical: 8,
+      }}
+    >
+      <MyazaText variant="bodySmall" color="#FFFFFF" style={{ fontWeight: '800', letterSpacing: 0.8 }}>
+        {side === 'back' ? 'BACK' : 'FRONT'}
+      </MyazaText>
+    </View>
+  );
+}
+
+/** Flag + document name, so the user can see WHICH document is expected. */
+export function DocumentPill({
+  country,
+  label,
+  top,
+}: {
+  country: string;
+  label: string;
+  top: number;
+}): React.ReactElement {
+  return (
+    <View style={{ position: 'absolute', top, left: 0, right: 0, alignItems: 'center' }}>
+      <View
+        style={{
+          flexDirection: 'row',
+          alignItems: 'center',
+          backgroundColor: SCRIM,
+          borderRadius: radius.full,
+          borderWidth: 1,
+          borderColor: 'rgba(255,255,255,0.18)',
+          paddingHorizontal: 12,
+          paddingVertical: 7,
+          maxWidth: '80%',
+        }}
+      >
+        {/* The flag carries the country on its own — a name beside it is the
+            same fact twice, and it reads faster at a glance than text. */}
+        {country ? (
+          <>
+            <CountryFlag country={country} size={26} />
+            <View style={{ width: 9 }} />
+          </>
+        ) : null}
+        <MyazaText
+          variant="bodyMedium"
+          color="#FFFFFF"
+          numberOfLines={1}
+          style={{ fontWeight: '700', flexShrink: 1 }}
+        >
+          {label}
+        </MyazaText>
+      </View>
+    </View>
+  );
+}

package/src/components/viewfinder/ImmersiveGuide.tsx

@@ -0,0 +1,174 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import Svg, { Defs, G, Line, Mask, Path, Rect } from 'react-native-svg';
+
+import { useTheme } from '../runtime';
+import { DocumentGhost } from './DocumentGhost';
+import type { DocumentFraming } from '../../capture';
+
+// ---------------------------------------------------------------------------
+// The full-screen document guide.
+//
+// A 1:1 port of the Flutter SDK's immersive viewfinder frame: a dimmed
+// surround, a rounded window at the document's own aspect, heavy corner
+// brackets, a faint grid inside, and a scan line sweeping down it.
+//
+// The grid and the sweep are not decoration — they are what makes a dim,
+// featureless preview read as "actively looking at something". Without them a
+// user holding a passport still gets no feedback until the shutter fires.
+// ---------------------------------------------------------------------------
+
+/** Share of the screen width the guide occupies (Flutter uses ~88%). */
+const GUIDE_WIDTH_FRACTION = 0.88;
+/** Grid divisions inside the window. */
+const GRID_COLS = 8;
+const GRID_ROWS = 6;
+
+export function ImmersiveGuide({
+  guideAspect,
+  primary,
+  width,
+  height,
+  framing,
+  showMrzBand,
+}: {
+  guideAspect: number;
+  primary: string;
+  width: number;
+  height: number;
+  /** Auto-capture's verdict for the current frame. */
+  framing: DocumentFraming;
+  /** Draw the ghost's machine-readable band (passport data pages carry one). */
+  showMrzBand: boolean;
+}): React.ReactElement {
+  const { colors } = useTheme();
+
+  // Each state answers a question the user is actually asking:
+  //   searching  → "is the camera even working?"  → neutral, sweeping
+  //   wrongShape/adjust → "what do I do?"         → amber, motion stops
+  //   holding/ready → "did it see it?"            → green, locked
+  //
+  // Amber for "I can see something but it isn't right" is distinct from the
+  // neutral searching state on purpose: it tells the user to ACT rather than
+  // wait, which is the difference between a fixable framing error and a camera
+  // that looks frozen.
+  const locked = framing === 'holding' || framing === 'ready';
+  const needsAction = framing === 'wrongShape' || framing === 'adjust';
+  const accent = locked ? colors.success : needsAction ? colors.warning : primary;
+
+  // Only dim once confident: dimming while still searching makes a dark room
+  // impossible to aim in.
+  const scrim = locked ? 0.45 : needsAction ? 0.25 : 0.18;
+  const gw = width * GUIDE_WIDTH_FRACTION;
+  const gh = gw / guideAspect;
+  const gx = (width - gw) / 2;
+  const gy = (height - gh) / 2;
+  const corner = Math.min(gw, gh) * 0.16;
+  const r = 14;
+
+  // The sweep runs the height of the window and repeats. Native driver: it is a
+  // pure transform, and a JS-driven animation over a live camera preview
+  // stutters exactly when the user is trying to hold still.
+  const sweep = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    const loop = Animated.loop(
+      Animated.timing(sweep, {
+        toValue: 1,
+        duration: 2600,
+        easing: Easing.inOut(Easing.ease),
+        useNativeDriver: true,
+      }),
+    );
+    if (locked) {
+      // Freeze once locked: continuing to sweep would imply we are still
+      // looking after we have decided.
+      sweep.stopAnimation();
+      return undefined;
+    }
+    loop.start();
+    return () => loop.stop();
+  }, [sweep, locked]);
+
+  return (
+    <>
+      <Svg style={{ position: 'absolute', inset: 0 }} width={width} height={height}>
+        <Defs>
+          <Mask id="guideWindow">
+            <Rect width={width} height={height} fill="white" />
+            <Rect x={gx} y={gy} width={gw} height={gh} rx={r} fill="black" />
+          </Mask>
+        </Defs>
+
+        {/* Everything outside the window is dimmed, so the document reads as
+            the lit subject even on a dark desk. */}
+        <Rect width={width} height={height} fill={`rgba(0,0,0,${scrim})`} mask="url(#guideWindow)" />
+
+        {/* Faint grid — alignment help that survives a low-contrast page. */}
+        <G opacity={0.28}>
+          {Array.from({ length: GRID_COLS - 1 }, (_, i) => (
+            <Line
+              key={`c${i}`}
+              x1={gx + (gw / GRID_COLS) * (i + 1)}
+              y1={gy}
+              x2={gx + (gw / GRID_COLS) * (i + 1)}
+              y2={gy + gh}
+              stroke={accent}
+              strokeWidth={0.75}
+            />
+          ))}
+          {Array.from({ length: GRID_ROWS - 1 }, (_, i) => (
+            <Line
+              key={`r${i}`}
+              x1={gx}
+              y1={gy + (gh / GRID_ROWS) * (i + 1)}
+              x2={gx + gw}
+              y2={gy + (gh / GRID_ROWS) * (i + 1)}
+              stroke={accent}
+              strokeWidth={0.75}
+            />
+          ))}
+        </G>
+
+        <Rect x={gx} y={gy} width={gw} height={gh} rx={r} fill="none" stroke={`${accent}66`} strokeWidth={1.5} />
+
+        {/* Corner brackets — the frame's actual edges, heavy enough to aim by. */}
+        {[
+          `M${gx},${gy + corner} L${gx},${gy + r} Q${gx},${gy} ${gx + r},${gy} L${gx + corner},${gy}`,
+          `M${gx + gw - corner},${gy} L${gx + gw - r},${gy} Q${gx + gw},${gy} ${gx + gw},${gy + r} L${gx + gw},${gy + corner}`,
+          `M${gx + gw},${gy + gh - corner} L${gx + gw},${gy + gh - r} Q${gx + gw},${gy + gh} ${gx + gw - r},${gy + gh} L${gx + gw - corner},${gy + gh}`,
+          `M${gx + corner},${gy + gh} L${gx + r},${gy + gh} Q${gx},${gy + gh} ${gx},${gy + gh - r} L${gx},${gy + gh - corner}`,
+        ].map((d, i) => (
+          <Path key={i} d={d} stroke={accent} strokeWidth={4} fill="none" strokeLinecap="round" />
+        ))}
+      </Svg>
+
+      {/* Scan line, above the SVG so it can be transform-animated natively. */}
+      <Animated.View
+        pointerEvents="none"
+        style={{
+          position: 'absolute',
+          left: gx,
+          top: gy,
+          width: gw,
+          height: 2,
+          backgroundColor: accent,
+          shadowColor: accent,
+          shadowOpacity: 0.9,
+          shadowRadius: 8,
+          shadowOffset: { width: 0, height: 0 },
+          transform: [
+            { translateY: sweep.interpolate({ inputRange: [0, 1], outputRange: [0, gh - 2] }) },
+          ],
+        }}
+      />
+      <DocumentGhost
+        x={gx}
+        y={gy}
+        width={gw}
+        height={gh}
+        showMrzBand={showMrzBand}
+        documentFound={framing !== 'none' && framing !== 'wrongShape'}
+      />
+    </>
+  );
+}

package/src/components/viewfinder/ImmersiveOverlay.tsx

@@ -0,0 +1,79 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../runtime';
+import { ImmersiveGuide } from './ImmersiveGuide';
+import { DocumentPill, RoundControl, SideBadge } from './ImmersiveControls';
+import { BottomBar } from './ImmersiveBottomBar';
+import type { DocumentFraming } from '../../capture';
+
+/**
+ * Everything drawn over the full-screen camera.
+ *
+ * Composed here rather than in CameraViewfinder so that file stays about camera
+ * wiring — and so the immersive layout can be read in one place against the
+ * Flutter screen it mirrors.
+ */
+export function ImmersiveOverlay(p: {
+  side: 'front' | 'back';
+  country: string;
+  documentLabel: string;
+  guideAspect: number;
+  hint: string;
+  hintIsAction: boolean;
+  progress: number;
+  busy: boolean;
+  torch: boolean;
+  hasTorch: boolean;
+  onToggleTorch: () => void;
+  onCapture: () => void;
+  onBack: (() => void) | null;
+  onUpload: (() => void) | null;
+  bottomInset: number;
+  width: number;
+  height: number;
+  topInset: number;
+  framing: DocumentFraming;
+  /** Passports carry an MRZ band; the ghost draws it so it is not cropped. */
+  showMrzBand: boolean;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <>
+      <ImmersiveGuide
+        guideAspect={p.guideAspect}
+        primary={colors.primary}
+        width={p.width}
+        height={p.height}
+        framing={p.framing}
+        showMrzBand={p.showMrzBand}
+      />
+      {p.onBack ? (
+        <RoundControl
+          icon="back"
+          label="Go back"
+          onPress={p.onBack}
+          style={{ top: p.topInset, left: spacing.md }}
+        />
+      ) : null}
+      <SideBadge side={p.side} top={p.topInset + 4} />
+      <DocumentPill country={p.country} label={p.documentLabel} top={p.topInset + 62} />
+      <BottomBar
+        hint={p.hint}
+        hintIsAction={p.hintIsAction}
+        allowUpload={!!p.onUpload}
+        onUpload={() => p.onUpload?.()}
+        onCapture={p.onCapture}
+        busy={p.busy}
+        ready
+        progress={p.progress}
+        hasTorch={p.hasTorch}
+        torch={p.torch}
+        onToggleTorch={p.onToggleTorch}
+        bottomInset={p.bottomInset}
+      />
+      <View pointerEvents="none" />
+    </>
+  );
+}

package/src/components/viewfinder/ViewfinderControls.tsx

@@ -0,0 +1,154 @@
+import React from 'react';
+import { ActivityIndicator, Pressable, View } from 'react-native';
+import Svg, { Circle } from 'react-native-svg';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../runtime';
+import { MyazaText } from '../Typography';
+import { Icon } from '../Icon';
+
+/** Top offset that clears the status bar when the camera runs full-bleed. */
+export function topInset(fill: boolean): number {
+  return fill ? spacing.xl + spacing.md : spacing.md;
+}
+
+/**
+ * The live instruction from the auto-capture gate.
+ *
+ * It replaced a static "align your ID" precisely because that told the user
+ * nothing about WHICH way to move — and the commonest failure, holding the
+ * document too close, is the one nobody guesses. Action hints take the primary
+ * colour so they read as something to do.
+ */
+export function HintBanner({
+  text,
+  isAction,
+  fill,
+}: {
+  text: string;
+  isAction: boolean;
+  fill: boolean;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View style={{ position: 'absolute', top: topInset(fill), left: 0, right: 0, alignItems: 'center' }}>
+      <View
+        style={{
+          backgroundColor: isAction ? colors.primary : 'rgba(0,0,0,0.4)',
+          paddingHorizontal: spacing.sm + 4,
+          paddingVertical: 6,
+          borderRadius: radius.full,
+          maxWidth: '90%',
+        }}
+      >
+        <MyazaText variant="bodySmall" color="#FFFFFF" style={{ textAlign: 'center' }}>
+          {text}
+        </MyazaText>
+      </View>
+    </View>
+  );
+}
+
+/** A round overlay button — the torch and the immersive back control. */
+export function OverlayButton({
+  icon,
+  onPress,
+  label,
+  active,
+  side,
+  fill,
+}: {
+  icon: 'lightbulb' | 'back';
+  onPress: () => void;
+  label: string;
+  active?: boolean;
+  side: 'left' | 'right';
+  fill: boolean;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      style={{
+        position: 'absolute',
+        top: topInset(fill),
+        [side]: spacing.md,
+        width: 36,
+        height: 36,
+        borderRadius: radius.full,
+        backgroundColor: active ? colors.primary : 'rgba(0,0,0,0.4)',
+        alignItems: 'center',
+        justifyContent: 'center',
+      }}
+    >
+      <Icon name={icon} size={18} color="#FFFFFF" />
+    </Pressable>
+  );
+}
+
+/**
+ * The shutter, with the stability dwell drawn around it.
+ *
+ * The ring is what tells a user who is holding steady that something is
+ * happening — without it, auto-capture looks like a camera doing nothing right
+ * up until it fires.
+ */
+export function Shutter({
+  onPress,
+  ready,
+  busy,
+  progress,
+}: {
+  onPress: () => void;
+  ready: boolean;
+  busy: boolean;
+  progress: number;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const R = 36;
+  const CIRC = 2 * Math.PI * R;
+
+  return (
+    <View style={{ position: 'absolute', bottom: spacing.lg, left: 0, right: 0, alignItems: 'center' }}>
+      {progress > 0 && progress < 1 ? (
+        <Svg width={80} height={80} style={{ position: 'absolute', bottom: -8 }}>
+          <Circle cx={40} cy={40} r={R} stroke="rgba(255,255,255,0.25)" strokeWidth={3} fill="none" />
+          <Circle
+            cx={40}
+            cy={40}
+            r={R}
+            stroke={colors.primary}
+            strokeWidth={3}
+            fill="none"
+            strokeLinecap="round"
+            strokeDasharray={CIRC}
+            strokeDashoffset={CIRC * (1 - progress)}
+            transform="rotate(-90 40 40)"
+          />
+        </Svg>
+      ) : null}
+      <Pressable
+        onPress={onPress}
+        disabled={busy || !ready}
+        accessibilityRole="button"
+        accessibilityLabel="Capture photo"
+        style={({ pressed }) => ({
+          width: 64,
+          height: 64,
+          borderRadius: radius.full,
+          backgroundColor: ready ? '#FFFFFF' : colors.gray400,
+          borderWidth: 4,
+          borderColor: ready ? colors.primary : colors.gray300,
+          alignItems: 'center',
+          justifyContent: 'center',
+          opacity: busy ? 0.6 : 1,
+          transform: [{ scale: pressed ? 0.94 : 1 }],
+        })}
+      >
+        {busy ? <ActivityIndicator color={colors.primary} /> : <Icon name="camera" size={24} color={ready ? colors.primary : '#FFFFFF'} />}
+      </Pressable>
+    </View>
+  );
+}

package/src/config/brand.ts

@@ -0,0 +1,97 @@
+/**
+ * Vendor brand constants for the SDK's own attribution — NOT the integrating
+ * org's branding (that is `useBranding()`, driven by `/api/kyc/config`).
+ *
+ * The platform is **Myaza Trust**, a product of **Myaza** (the parent company).
+ * Always the full product name: bare "Myaza" is the company, and a pipe
+ * ("Myaza | Trust") reads as a separator between two items rather than one
+ * name. See the naming rule in kyc-dashboard/CLAUDE.md.
+ */
+export const PRODUCT_NAME = 'Myaza Trust';
+
+/** The product site — where "who are these people?" gets answered. */
+export const PRODUCT_URL = 'https://trust.myaza.co';
+
+/**
+ * Wordmark ink. The icon keeps its brand colours in both themes; only the
+ * "myaza" lettering flips. These are the exact values the dashboard's own Logo
+ * renders (logo.svg / logo-white.svg), so the mark is brand-accurate rather
+ * than tinted to whatever the sheet's text colour happens to be.
+ */
+export const WORDMARK_LIGHT = '#19156F';
+export const WORDMARK_DARK = '#F6F5FE';
+
+/**
+ * End-user legal documents linked from the consent screen. These are MYAZA's
+ * terms — the person consents to us processing their data as the verification
+ * provider — so they are never org-overridable.
+ */
+export const TERMS_URL = 'https://trust.myaza.co/legal/terms';
+export const PRIVACY_URL = 'https://trust.myaza.co/legal/privacy';
+
+/**
+ * Version of the consent wording. Consent is given by ACTING (tapping
+ * Continue) rather than ticking a box, so bump this whenever the copy changes
+ * materially and store it with the verification — otherwise nothing proves
+ * which disclosure was on screen. Keep in step with the web SDK's value.
+ */
+export const CONSENT_VERSION = '2026-08-06.1';
+
+/**
+ * Tones the footer mark may use — the design system's INK and LIGHT text
+ * colours, not the brand purple.
+ *
+ * Attribution, not advertising. A saturated purple mark is the loudest thing in
+ * the footer on an org whose palette is yellow or green: it draws the eye to the
+ * least important element on screen and reads as a clash rather than a
+ * signature. Every comparable vendor mark (Stripe, Plaid, Persona) is monochrome
+ * for the same reason.
+ *
+ * Nothing is lost by it — the logo ICON keeps its fixed brand fills, so the
+ * Myaza identity is still carried by the mark itself while the text recedes.
+ * These two are the design system's own text tones, so this stays on-brand
+ * rather than arbitrary black-on-white.
+ *
+ * Mirrors the web SDK's `lib/brand.ts` — keep the list and the rule in step.
+ */
+const MARK_TONES = ['#070330', '#F6F5FE'] as const;
+
+/** WCAG AA for the small text this renders at. */
+const MIN_MARK_CONTRAST = 4.5;
+
+function relativeLuminance(hex: string): number {
+  const h = hex.replace('#', '');
+  const channel = (i: number): number => {
+    const s = parseInt(h.slice(i, i + 2), 16) / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(0) + 0.7152 * channel(2) + 0.0722 * channel(4);
+}
+
+function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * The mark tone that stays legible on `background`.
+ *
+ * The footer mark must NOT follow the org's palette: it is our attribution, and
+ * an org whose brand is close to ours would otherwise get a mark that either
+ * stops reading as Myaza or disappears into the background entirely. Chosen by
+ * CONTRAST rather than by light/dark, because an org can set any background —
+ * including mid-tones where neither variant is obviously right.
+ *
+ * Falls back to the most visible tone when none clears AA, so the answer is
+ * always the best available rather than a fixed guess.
+ */
+export function brandMarkColor(background: string): string {
+  const bg = /^#[0-9a-f]{6}$/i.test(background.trim()) ? background.trim() : '#FFFFFF';
+  for (const tone of MARK_TONES) {
+    if (contrastRatio(tone, bg) >= MIN_MARK_CONTRAST) return tone;
+  }
+  return MARK_TONES.reduce((best, tone) =>
+    contrastRatio(tone, bg) > contrastRatio(best, bg) ? tone : best,
+  );
+}