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

package/src/components/theme-provider.tsx

@@ -0,0 +1,89 @@
+import React, { createContext, useContext, useMemo, useState } from 'react';
+import { useColorScheme } from 'react-native';
+
+import { resolveColors, type MyazaColorScheme, type ThemeMode , applyRadiusScale } from '../config/theme';
+import type { KYCAppearance } from '../types/config';
+import { useMyazaFonts } from './fonts';
+import { useBrandFonts } from './brand-font';
+
+// ---------------------------------------------------------------------------
+// Theme context.
+//
+// Split from the runtime provider because theming and the flow have different
+// lifetimes: the trigger button and the workflow-resolution barrier both need
+// colours BEFORE there is a resolved config to build a store from. Nesting is
+// supported and the inner provider wins, which is how a resolved workflow's
+// appearance takes over from the props' once it lands.
+// ---------------------------------------------------------------------------
+
+export interface ThemeValue {
+  mode: ThemeMode;
+  colors: MyazaColorScheme;
+  setMode: (mode: ThemeMode) => void;
+  toggle: () => void;
+  /** True once Space Grotesk + Karla are loaded (system font until then). */
+  fontsLoaded: boolean;
+  /** Org font families from `appearance`, when set. Empty object otherwise. */
+  brandFonts: { body?: string; heading?: string };
+}
+
+const ThemeContext = createContext<ThemeValue | null>(null);
+
+export function MyazaThemeProvider({
+  appearance,
+  children,
+}: {
+  appearance?: KYCAppearance;
+  children: React.ReactNode;
+}): React.ReactElement {
+  // `theme: 'system'` follows the DEVICE's colour scheme — live, so an
+  // OS-level switch mid-flow repaints — until the in-flow toggle picks a mode
+  // explicitly (`override`), which then wins for the rest of the session.
+  // 'light'/'dark' (and unset → light) pin the mode exactly as before.
+  const systemScheme = useColorScheme();
+  const configured = appearance?.theme;
+  const [override, setOverride] = useState<ThemeMode | null>(
+    configured === 'system' ? null : configured ?? 'light',
+  );
+  const mode: ThemeMode = override ?? (systemScheme === 'dark' ? 'dark' : 'light');
+  const setMode = setOverride as (mode: ThemeMode) => void;
+  const colors = useMemo(() => resolveColors(mode, appearance), [mode, appearance]);
+  const fontsLoaded = useMyazaFonts();
+
+  // Applied here rather than at launch so a nested provider (a resolved
+  // workflow's appearance taking over from the props') re-scales too. The
+  // radius scale is a module-level object read during render, so setting it
+  // while rendering this provider lands before any child reads it.
+  applyRadiusScale(appearance?.borderRadius);
+
+  // Only families that are actually REGISTERED come back. Applying a name RN
+  // can't resolve is what made a configured font silently fall back to system —
+  // the hook loads it first, then re-renders with it.
+  const brandFonts = useBrandFonts(appearance?.fontFamily, appearance?.headingFontFamily);
+
+  const value = useMemo<ThemeValue>(
+    () => ({
+      mode,
+      colors,
+      setMode,
+      // Flip from the EFFECTIVE mode (which may be system-derived), so the
+      // first toggle out of system mode lands on the opposite of what the
+      // user is currently seeing.
+      toggle: () => setOverride(mode === 'dark' ? 'light' : 'dark'),
+      fontsLoaded,
+      brandFonts,
+    }),
+    [mode, colors, fontsLoaded, brandFonts],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+/** Theme colors + light/dark mode controls. */
+export function useTheme(): ThemeValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error('Myaza KYC components must be rendered inside <MyazaThemeProvider>.');
+  }
+  return ctx;
+}

package/src/components/useWorkflowMount.ts

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { KYCError } from '../types/verification';
+import type { MyazaKYCConfig, ResolvedKYCConfig } from '../types/config';
+import type { ServerConfigState } from '../store/serverConfig';
+import { requireCountry, resolveWorkflow } from '../services/workflowGate';
+
+// ---------------------------------------------------------------------------
+// Resolving a workflow, separated from anything that draws.
+//
+// This used to live inside the gate, which lived inside the modal — so opening
+// the SDK presented a modal FIRST and resolved afterwards. That ordering is
+// visible: the modal, its chrome and its loader all had to be painted before
+// the workflow's appearance was known, so they came up in the default brand and
+// then changed colour underneath the user. A flash of the wrong brand is worse
+// than a moment of nothing, because it looks like someone else's product.
+//
+// Hoisting resolution out here lets the caller wait for a settled config and
+// present a modal that is correctly branded on its first frame.
+//
+// It also PREFETCHES: resolution starts when the SDK mounts, not when the
+// button is tapped, so by tap time the answer is usually already in hand. That
+// matters — gating the modal without prefetching would just trade a wrong
+// colour for a dead press, which reads as a broken button.
+// ---------------------------------------------------------------------------
+
+export interface ResolvedMount {
+  config: ResolvedKYCConfig;
+  /** Preloaded server config when a workflow supplied one; else undefined. */
+  serverConfig?: ServerConfigState;
+}
+
+export type MountState =
+  | { status: 'resolving' }
+  | { status: 'ready'; mount: ResolvedMount }
+  | { status: 'error'; error: KYCError };
+
+export interface WorkflowMount {
+  state: MountState;
+  /** Re-run a failed resolution. */
+  retry: () => void;
+  /**
+   * Re-fetch before opening, so a flow edited since the app started is picked
+   * up.
+   *
+   * The prefetch below is a warm-up, NOT a cache: resolving once at mount and
+   * reusing it meant an org could publish a change, reopen the SDK, and still
+   * get the config fetched when the app launched — with nothing to indicate the
+   * screen was stale. A workflow is edited far more often than an app is
+   * relaunched, so freshness has to win over saving one request.
+   */
+  refresh: () => void;
+}
+
+/** Synchronous settle for a props-only mount — no network, no barrier. */
+export function settleWithoutWorkflow(config: MyazaKYCConfig): MountState {
+  try {
+    return { status: 'ready', mount: { config: requireCountry(config) } };
+  } catch (err) {
+    return {
+      status: 'error',
+      error: err instanceof KYCError ? err : new KYCError('unknown', String(err)),
+    };
+  }
+}
+
+export function useWorkflowMount(config: MyazaKYCConfig): WorkflowMount {
+  // A props-only mount settles synchronously, so the common case never reports
+  // `resolving` for even one frame and the modal opens with no added latency.
+  const initial = useRef<MountState | null>(null);
+  if (initial.current === null) {
+    initial.current = config.workflowId ? { status: 'resolving' } : settleWithoutWorkflow(config);
+  }
+  const [state, setState] = useState<MountState>(initial.current);
+  const [attempt, setAttempt] = useState(0);
+
+  // Consumers spread props into a fresh object every render, so depending on
+  // `config` itself would abort and restart resolution on each of the
+  // consumer's re-renders — a loop that never settles. What resolution actually
+  // depends on is the key, the host and the workflow id; the rest is read from
+  // the ref at call time.
+  const configRef = useRef(config);
+  configRef.current = config;
+  const { workflowId, apiKey, devUrl } = config;
+
+  useEffect(() => {
+    if (!workflowId) return;
+    const controller = new AbortController();
+    let live = true;
+    setState({ status: 'resolving' });
+
+    resolveWorkflow(configRef.current, controller.signal)
+      .then((result) => {
+        if (!live) return;
+        setState({ status: 'ready', mount: result });
+      })
+      .catch((err: unknown) => {
+        // An abort is this component going away, not a failure to report.
+        if (!live || controller.signal.aborted) return;
+        setState({
+          status: 'error',
+          error: err instanceof KYCError ? err : new KYCError('unknown', String(err)),
+        });
+      });
+
+    return () => {
+      live = false;
+      controller.abort();
+    };
+    // `attempt` re-runs this on Retry.
+  }, [workflowId, apiKey, devUrl, attempt]);
+
+  const bump = useCallback(() => setAttempt((n) => n + 1), []);
+
+  return { state, retry: bump, refresh: bump };
+}

package/src/components/viewfinder/CardGuide.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import Svg, { Defs, Mask, Path, Rect } from 'react-native-svg';
+
+// The card window within a 3:4 viewBox, centred. Height follows the per-ID
+// guide aspect so the overlay matches the auto-crop (cropCardRegion) — a guide
+// that disagrees with the crop teaches the user to frame it wrong.
+const VB_W = 100;
+const VB_H = 133;
+const GX = 6;
+const GW = 88;
+const C = 7; // corner accent length
+
+/**
+ * The dimmed surround + dashed document window + primary corner accents.
+ *
+ * Split out of CameraViewfinder purely for the 200-line rule: it is static
+ * geometry with no state, and keeping it here leaves the viewfinder itself
+ * about camera wiring rather than path maths.
+ */
+export function CardGuide({
+  guideAspect,
+  primary,
+}: {
+  guideAspect: number;
+  primary: string;
+}): React.ReactElement {
+  const GH = GW / guideAspect;
+  const GY = (VB_H - GH) / 2;
+
+  return (
+    <Svg
+      style={{ position: 'absolute', inset: 0 }}
+      viewBox={`0 0 ${VB_W} ${VB_H}`}
+      preserveAspectRatio="none"
+    >
+      <Defs>
+        <Mask id="cardMask">
+          <Rect width={VB_W} height={VB_H} fill="white" />
+          <Rect x={GX} y={GY} width={GW} height={GH} rx={3} fill="black" />
+        </Mask>
+      </Defs>
+      <Rect width={VB_W} height={VB_H} fill="rgba(0,0,0,0.55)" mask="url(#cardMask)" />
+      <Rect
+        x={GX}
+        y={GY}
+        width={GW}
+        height={GH}
+        rx={3}
+        fill="none"
+        stroke="rgba(255,255,255,0.85)"
+        strokeWidth={0.6}
+        strokeDasharray="5 3"
+      />
+      <Path d={`M${GX},${GY + C} L${GX},${GY} L${GX + C},${GY}`} stroke={primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+      <Path d={`M${GX + GW - C},${GY} L${GX + GW},${GY} L${GX + GW},${GY + C}`} stroke={primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+      <Path d={`M${GX + GW},${GY + GH - C} L${GX + GW},${GY + GH} L${GX + GW - C},${GY + GH}`} stroke={primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+      <Path d={`M${GX + C},${GY + GH} L${GX},${GY + GH} L${GX},${GY + GH - C}`} stroke={primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+    </Svg>
+  );
+}

package/src/components/viewfinder/DocumentGhost.tsx

@@ -0,0 +1,149 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import Svg, { Rect } from 'react-native-svg';
+
+// ---------------------------------------------------------------------------
+// Document ghost.
+//
+// A faint outline of the document's LAYOUT inside the capture guide, shown for
+// a few seconds when the camera opens: where the portrait sits, where the
+// printed details run, and — on a passport — the machine-readable band across
+// the bottom.
+//
+// The guide rectangle says WHERE to put the document. It does not say which way
+// round, and the commonest passport mistake is framing the page with the MRZ
+// cropped off the bottom edge — which auto-capture then refuses, because that
+// band is the chip's key and the proof the page is a passport.
+//
+// Placeholder BARS and BLOCKS, never literal drawings: nothing here is meant to
+// be read, only recognised as a shape. A sketched face would be a worse thing
+// to show a user than nothing at all.
+//
+// Ported from the Flutter SDK's DocumentGhost — geometry included, so the two
+// cannot drift.
+// ---------------------------------------------------------------------------
+
+/** How long the ghost stays before fading. Long enough to register while the
+ *  user is still lifting the document into frame; short enough to be gone
+ *  before it can obscure the document itself. */
+const GHOST_MS = 5000;
+
+const LINE = 'rgba(255,255,255,0.30)';
+const FILL = 'rgba(255,255,255,0.12)';
+const BAND = 'rgba(255,255,255,0.35)';
+
+export function DocumentGhost({
+  x,
+  y,
+  width,
+  height,
+  showMrzBand,
+  documentFound,
+}: {
+  /** The guide rect, in the same coordinates the overlay uses. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Passport data pages carry a machine-readable band. */
+  showMrzBand: boolean;
+  /** Hides it early: once a document is framed the guidance has done its job
+   *  and would only sit on top of the thing being captured. */
+  documentFound: boolean;
+}): React.ReactElement | null {
+  const opacity = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    Animated.timing(opacity, {
+      toValue: 1,
+      duration: 400,
+      easing: Easing.out(Easing.ease),
+      useNativeDriver: true,
+    }).start();
+    const t = setTimeout(() => {
+      Animated.timing(opacity, {
+        toValue: 0,
+        duration: 600,
+        useNativeDriver: true,
+      }).start();
+    }, GHOST_MS);
+    return () => clearTimeout(t);
+  }, [opacity]);
+
+  useEffect(() => {
+    if (!documentFound) return;
+    Animated.timing(opacity, { toValue: 0, duration: 250, useNativeDriver: true }).start();
+  }, [documentFound, opacity]);
+
+  if (width <= 0 || height <= 0) return null;
+
+  // Inset so the layout sits inside the document's edge, not on the guide.
+  const pad = width * 0.07;
+  const pl = x + pad;
+  const pt = y + pad;
+  const pw = width - pad * 2;
+  const ph = height - pad * 2;
+
+  const photoW = pw * 0.24;
+  const photoH = ph * (showMrzBand ? 0.46 : 0.58);
+
+  // Alternating lengths so it reads as printed fields rather than a barcode.
+  const barLeft = pl + photoW + pw * 0.06;
+  const barMax = pl + pw - barLeft;
+  const widths = [1.0, 0.62, 0.85, 0.5];
+  const barH = Math.min(7, Math.max(3, photoH * 0.1));
+
+  const bandH = Math.min(8, Math.max(3, ph * 0.055));
+  const bandTop = pt + ph - bandH * 3.2;
+
+  return (
+    <Animated.View pointerEvents="none" style={{ position: 'absolute', inset: 0, opacity }}>
+      <Svg width="100%" height="100%">
+        {/* Portrait block — a block, not a face. The proportion identifies it. */}
+        <Rect x={pl} y={pt} width={photoW} height={photoH} rx={4} fill={FILL} />
+        <Rect
+          x={pl}
+          y={pt}
+          width={photoW}
+          height={photoH}
+          rx={4}
+          fill="none"
+          stroke={LINE}
+          strokeWidth={1.5}
+        />
+
+        {widths.map((w, i) => {
+          const by = pt + photoH * (0.08 + i * 0.26);
+          if (by + barH > pt + photoH) return null;
+          return (
+            <Rect
+              key={i}
+              x={barLeft}
+              y={by}
+              width={barMax * w}
+              height={barH}
+              rx={barH / 2}
+              fill={FILL}
+            />
+          );
+        })}
+
+        {/* The reason the ghost exists: it shows the band belongs INSIDE the
+            frame, which is the edge users most often crop away. */}
+        {showMrzBand
+          ? [0, 1].map((i) => (
+              <Rect
+                key={`b${i}`}
+                x={pl}
+                y={bandTop + i * bandH * 1.9}
+                width={pw * (i === 0 ? 1 : 0.93)}
+                height={bandH}
+                rx={bandH / 2}
+                fill={BAND}
+              />
+            ))
+          : null}
+      </Svg>
+    </Animated.View>
+  );
+}

package/src/components/viewfinder/ImmersiveBottomBar.tsx

@@ -0,0 +1,172 @@
+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';
+
+const SCRIM = 'rgba(0,0,0,0.55)';
+
+/**
+ * Fixed slots either side of the shutter.
+ *
+ * The torch is a CAPTURE control, so it sits beside the shutter where the thumb
+ * already is — not out in a corner. Equal slots keep the shutter centred
+ * whether or not the device has a flash unit to show.
+ */
+const SIDE_SLOT = 72;
+
+/** Hint + upload escape + shutter + torch, stacked at the bottom. */
+export function BottomBar({
+  hint,
+  hintIsAction,
+  allowUpload,
+  onUpload,
+  onCapture,
+  busy,
+  ready,
+  progress,
+  hasTorch,
+  torch,
+  onToggleTorch,
+  bottomInset,
+}: {
+  hint: string;
+  hintIsAction: boolean;
+  allowUpload: boolean;
+  onUpload: () => void;
+  onCapture: () => void;
+  busy: boolean;
+  ready: boolean;
+  progress: number;
+  hasTorch: boolean;
+  torch: boolean;
+  onToggleTorch: () => void;
+  bottomInset: number;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const R = 40;
+  const CIRC = 2 * Math.PI * R;
+
+  return (
+    <View
+      style={{
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: bottomInset + spacing.lg,
+        alignItems: 'center',
+      }}
+    >
+      <View
+        style={{
+          backgroundColor: hintIsAction ? colors.primary : SCRIM,
+          borderRadius: radius.full,
+          paddingHorizontal: spacing.md,
+          paddingVertical: 10,
+          maxWidth: '92%',
+        }}
+      >
+        <MyazaText variant="bodyMedium" color="#FFFFFF" style={{ textAlign: 'center' }}>
+          {hint}
+        </MyazaText>
+      </View>
+
+      {allowUpload ? (
+        <Pressable onPress={onUpload} style={{ marginTop: spacing.md }} accessibilityRole="button">
+          <View style={{ flexDirection: 'row', alignItems: 'center' }}>
+            <Icon name="upload" size={18} color="#FFFFFF" />
+            <View style={{ width: 8 }} />
+            <MyazaText variant="bodyMedium" color="#FFFFFF">
+              Upload a photo instead
+            </MyazaText>
+          </View>
+        </Pressable>
+      ) : null}
+
+      <View style={{ height: spacing.md }} />
+
+      <View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'center', alignSelf: 'stretch' }}>
+        <View style={{ width: SIDE_SLOT }} />
+        <View style={{ flex: 1, alignItems: 'center' }}>
+          {/* The dwell, drawn around the shutter — a user holding steady can see
+              it working instead of wondering whether to press. */}
+          {progress > 0 && progress < 1 ? (
+            <Svg width={88} height={88} style={{ position: 'absolute', top: -4 }}>
+              <Circle
+                cx={44}
+                cy={44}
+                r={R}
+                stroke={colors.primary}
+                strokeWidth={3}
+                fill="none"
+                strokeLinecap="round"
+                strokeDasharray={CIRC}
+                strokeDashoffset={CIRC * (1 - progress)}
+                transform="rotate(-90 44 44)"
+              />
+            </Svg>
+          ) : null}
+          <Pressable
+            onPress={onCapture}
+            disabled={busy || !ready}
+            accessibilityRole="button"
+            accessibilityLabel="Capture photo"
+            style={({ pressed }) => ({
+              width: 80,
+              height: 80,
+              borderRadius: radius.full,
+              borderWidth: 4,
+              borderColor: '#FFFFFF',
+              backgroundColor: 'transparent',
+              alignItems: 'center',
+              justifyContent: 'center',
+              opacity: busy ? 0.6 : 1,
+              transform: [{ scale: pressed ? 0.94 : 1 }],
+            })}
+          >
+            <View
+              style={{
+                width: 62,
+                height: 62,
+                borderRadius: radius.full,
+                backgroundColor: ready ? colors.primary : colors.gray400,
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              {busy ? <ActivityIndicator color="#FFFFFF" /> : <Icon name="scan-line" size={26} color="#FFFFFF" />}
+            </View>
+          </Pressable>
+        </View>
+        <View style={{ width: SIDE_SLOT, alignItems: 'center' }}>
+          {hasTorch ? (
+            <Pressable
+              onPress={onToggleTorch}
+              accessibilityRole="button"
+              accessibilityLabel={torch ? 'Turn off the torch' : 'Turn on the torch'}
+              style={{
+                width: 36,
+                height: 36,
+                borderRadius: radius.full,
+                // Inverted when on, so "lit" reads at a glance rather than
+                // needing the icon to be decoded.
+                backgroundColor: torch ? '#FFFFFF' : 'rgba(0,0,0,0.45)',
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              <Icon
+                name={torch ? 'zap' : 'zap-off'}
+                size={18}
+                color={torch ? colors.primary : '#FFFFFF'}
+              />
+            </Pressable>
+          ) : null}
+        </View>
+      </View>
+    </View>
+  );
+}