@myazahq/kyc-sdk-react-native 2.5.0 → 3.0.0

package/src/components/PresenceBlocks.tsx

@@ -0,0 +1,153 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, View } from 'react-native';
+
+import { MyazaText } from './Typography';
+import { MilestoneTrack, type Milestone } from './MilestoneTrack';
+import { useReduceMotion } from './StaggerIn';
+import { radius, spacing } from '../config/theme';
+import { useTheme } from './theme-provider';
+
+// ---------------------------------------------------------------------------
+// The success screen's presence card, drawn as a LIVE PROCESS rather than a
+// notice: the check began the moment they submitted, so the card should feel
+// like something is already quietly working, because it is.
+//
+// Its milestones are the same three the intro gate promises, one frame later —
+// keep the two, and the web and Flutter SDKs, in lockstep.
+//
+// The standalone "presence consent notice" that used to live here is gone: the
+// disclosures belong on the intro gate, and a second copy on the address step
+// was one more place for the consent wording to drift.
+// ---------------------------------------------------------------------------
+
+const MILESTONES: readonly Milestone[] = [
+  {
+    icon: 'map-pin-check',
+    stage: 'Today',
+    title: 'Check started',
+    caption: 'Your pin is saved. Keep location on.',
+    state: 'active',
+  },
+  {
+    icon: 'radar',
+    stage: 'Next few days',
+    title: 'Quiet check-ins',
+    caption: 'Your phone confirms it is at your address now and then.',
+    state: 'ahead',
+  },
+  {
+    icon: 'bell-ring',
+    stage: 'Then',
+    title: 'Confirmed',
+    caption: 'You get a notification. That is it.',
+    state: 'ahead',
+  },
+];
+
+export function PresenceExpectations(): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        alignSelf: 'stretch',
+        marginTop: spacing.lg,
+        borderWidth: 1,
+        borderColor: `${colors.primary}26`,
+        borderRadius: radius.md,
+        overflow: 'hidden',
+      }}
+    >
+      <View
+        style={{
+          backgroundColor: `${colors.primary}0F`,
+          paddingHorizontal: spacing.md,
+          paddingTop: spacing.md,
+          paddingBottom: spacing.sm + 4,
+        }}
+      >
+        <View
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            alignSelf: 'flex-start',
+            gap: spacing.sm,
+            paddingHorizontal: spacing.sm + 2,
+            paddingVertical: 4,
+            borderRadius: radius.full,
+            backgroundColor: `${colors.primary}1A`,
+          }}
+        >
+          <LiveDot />
+          <MyazaText
+            variant="bodySmall"
+            color={colors.primary}
+            style={{
+              fontSize: 11,
+              fontWeight: '600',
+              letterSpacing: 0.6,
+              textTransform: 'uppercase',
+            }}
+          >
+            Address check active
+          </MyazaText>
+        </View>
+        <MyazaText variant="bodyMedium" style={{ fontWeight: '600', marginTop: spacing.sm }}>
+          Your address confirms itself from here
+        </MyazaText>
+        <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ marginTop: 2 }}>
+          Nothing else for you to do. Carry on as normal.
+        </MyazaText>
+      </View>
+
+      {/* Web's h-8 nodes here, against the primer's h-10. */}
+      <MilestoneTrack milestones={MILESTONES} nodeSize={32} />
+    </View>
+  );
+}
+
+/** The badge's pulse — the one thing on the card that says "running now". */
+function LiveDot(): React.ReactElement {
+  const { colors } = useTheme();
+  const reduceMotion = useReduceMotion();
+  const pulse = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (reduceMotion) return undefined;
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, { toValue: 1, duration: 900, useNativeDriver: true }),
+        Animated.timing(pulse, { toValue: 0, duration: 0, useNativeDriver: true }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [pulse, reduceMotion]);
+
+  return (
+    <View style={{ width: 8, height: 8, alignItems: 'center', justifyContent: 'center' }}>
+      {reduceMotion ? null : (
+        <Animated.View
+          style={{
+            position: 'absolute',
+            width: 8,
+            height: 8,
+            borderRadius: radius.full,
+            backgroundColor: colors.primary,
+            opacity: pulse.interpolate({ inputRange: [0, 1], outputRange: [0.6, 0] }),
+            transform: [
+              { scale: pulse.interpolate({ inputRange: [0, 1], outputRange: [1, 2.2] }) },
+            ],
+          }}
+        />
+      )}
+      <View
+        style={{
+          width: 8,
+          height: 8,
+          borderRadius: radius.full,
+          backgroundColor: colors.primary,
+        }}
+      />
+    </View>
+  );
+}

package/src/components/RequiredDocumentPill.tsx

@@ -0,0 +1,114 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { Icon } from './Icon';
+import { useTheme } from './runtime';
+import { MyazaText } from './Typography';
+
+/**
+ * "Required: <document>" — which document this step expects, on the screens
+ * either side of the camera (the ready primer and the review).
+ *
+ * The header names the document too, but this is the last thing in view when
+ * the applicant is deciding whether they have the right one in hand, and on a
+ * two-sided ID it is the only place that says which SIDE is being asked for
+ * and how far through they are.
+ *
+ * Mirrors the web SDK's badge in DocumentCaptureStep and Flutter's
+ * `_RequiredPill`: same Lucide glyph, same primary tint, same wording.
+ */
+export function RequiredDocumentPill({
+  idTypeLabel,
+  sideBadge,
+  stepLabel,
+}: {
+  idTypeLabel: string;
+  /** "Front Side" / "Back Side" — two-sided documents only. */
+  sideBadge?: string | null;
+  /** "Step 1 of 2" — two-sided documents only. */
+  stepLabel?: string | null;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const hasMeta = Boolean(sideBadge || stepLabel);
+  return (
+    <View
+      style={{
+        flexDirection: 'row',
+        alignItems: 'center',
+        flexWrap: 'wrap',
+        // Column and row gaps are set separately: when this wraps, the two
+        // groups need breathing room vertically too, and a single `gap` gives
+        // the wrapped row the same spacing as the inline one by accident.
+        columnGap: spacing.sm,
+        rowGap: spacing.xs,
+        paddingHorizontal: spacing.md,
+        paddingVertical: spacing.sm,
+        borderRadius: radius.md,
+        borderWidth: 1,
+        borderColor: colors.primary200,
+        backgroundColor: colors.primary50,
+      }}
+      // One statement to a screen reader; the parts read as a sentence
+      // rather than three disconnected fragments.
+      accessible
+      accessibilityLabel={[`Required: ${idTypeLabel}`, sideBadge, stepLabel]
+        .filter(Boolean)
+        .join(', ')}
+    >
+      {/* What the applicant has to be holding. Shrinks and wraps within its
+          own box before it pushes anything else off the line, because the
+          document name is the one part of this that cannot be abbreviated —
+          "Permanent Voter's Card" truncated is a different document. */}
+      <View
+        style={{
+          flexDirection: 'row',
+          alignItems: 'center',
+          gap: spacing.xs,
+          flexShrink: 1,
+          minWidth: 0,
+        }}
+      >
+        <Icon name="credit-card" size={16} color={colors.primary} />
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600' }}>
+          Required:
+        </MyazaText>
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ flexShrink: 1 }}>
+          {idTypeLabel}
+        </MyazaText>
+      </View>
+      {/* Side and progress travel TOGETHER. They are one thought — which half
+          of a two-sided document this is — and on a narrow screen they drop to
+          a second line as a pair.
+          The step label used to carry `marginLeft: 'auto'`, which fights
+          `flexWrap`: auto-margin assumes spare space on the line, wrapping
+          means there is none. So on a long document name it wrapped alone and
+          was then flung to the right edge, leaving an orphaned "Step 1 of 2"
+          under an empty gap. Seen on a Galaxy S24 with "Permanent Voter's
+          Card". Grouping them makes the wrap look deliberate instead. */}
+      {hasMeta ? (
+        <View style={{ flexDirection: 'row', alignItems: 'center', gap: spacing.xs }}>
+          {sideBadge ? (
+            <View
+              style={{
+                paddingHorizontal: spacing.sm,
+                paddingVertical: 2,
+                borderRadius: radius.full,
+                backgroundColor: colors.primary100,
+              }}
+            >
+              <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600' }}>
+                {sideBadge}
+              </MyazaText>
+            </View>
+          ) : null}
+          {stepLabel ? (
+            <MyazaText variant="bodySmall" color={colors.textSecondary}>
+              {stepLabel}
+            </MyazaText>
+          ) : null}
+        </View>
+      ) : null}
+    </View>
+  );
+}

package/src/components/StepHeader.tsx

@@ -17,6 +17,10 @@ import { CountryFlag } from './CountryFlag';
 const BACK_SIZE = 40;
 const BACK_FOOTPRINT = BACK_SIZE + spacing.sm;
 
+// One line of heading2 (fontSize 20). The flag is centred inside a box of this
+// height so it lands on the first line whether the title wraps or not.
+const FLAG_LINE_HEIGHT = 26;
+
 export interface StepHeaderProps {
   title: string;
   description?: string | null;
@@ -44,13 +48,29 @@ export function StepHeader({ title, description, onBack, country }: StepHeaderPr
             />
           </View>
         ) : null}
-        <View style={{ flex: 1, flexDirection: 'row', alignItems: 'center' }}>
+        {/* `flex-start`, not `center`. A long document name wraps to two lines
+            on a small screen ("Capture Your Permanent Voter's Card" does at
+            360dp), and centring the flag against the whole block floated it in
+            the gap between the lines, attached to neither. Anchored to the top
+            it reads as a marker on the title, wherever the text wraps.
+            Seen on a Galaxy S24. */}
+        <View style={{ flex: 1, flexDirection: 'row', alignItems: 'flex-start' }}>
           <MyazaText variant="heading2" numberOfLines={2} style={{ flexShrink: 1 }}>
             {title}
           </MyazaText>
           {country ? (
-            <View style={{ marginLeft: spacing.sm }}>
-              <CountryFlag country={country} size={20} />
+            // The flag box is the height of one line of heading2, with the flag
+            // centred in it — so it sits on the first line's optical centre
+            // rather than its top edge, and does not have to be re-nudged if
+            // the type scale moves.
+            <View
+              style={{
+                marginLeft: spacing.sm,
+                height: FLAG_LINE_HEIGHT,
+                justifyContent: 'center',
+              }}
+            >
+              <CountryFlag country={country} size={18} />
             </View>
           ) : null}
         </View>

package/src/components/StepView.tsx

@@ -12,6 +12,12 @@ import { SubmittedStep } from '../screens/SubmittedStep';
 import { QuestionnaireStep } from '../screens/QuestionnaireStep';
 import { ContactVerificationStep } from '../screens/ContactVerificationStep';
 import { ProofOfAddressStep } from '../screens/ProofOfAddressStep';
+import {
+  AddressEntranceStep,
+  AddressPinStep,
+  AddressReviewStep,
+  AddressSearchStep,
+} from '../screens/address';
 import { CountrySelectStep } from '../screens/CountrySelectStep';
 import { BusinessDetailsStep } from '../screens/BusinessDetailsStep';
 import { BusinessKeyPeopleStep } from '../screens/BusinessKeyPeopleStep';
@@ -78,6 +84,17 @@ function stepScreen(step: KYCStep, onClose: () => void): React.ReactElement {
       return <ContactVerificationStep key="contact-phone" channel="phone" />;
     case 'proof-of-address':
       return <ProofOfAddressStep />;
+    // The address flow, in order: find it, confirm it, show it, commit it.
+    // 'address-collection' is the PIN step and keeps that wire name so older
+    // session progress restores cleanly.
+    case 'address-search':
+      return <AddressSearchStep />;
+    case 'address-collection':
+      return <AddressPinStep />;
+    case 'address-entrance':
+      return <AddressEntranceStep />;
+    case 'address-review':
+      return <AddressReviewStep />;
     case 'country-select':
       return <CountrySelectStep />;
     case 'business-details':

package/src/components/StickyActions.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { ScrollView, StyleSheet, View } from 'react-native';
+
+import { spacing } from '../config/theme';
+import { useTheme } from './runtime';
+
+/**
+ * A step's primary actions, held at the bottom edge of a viewport-filling
+ * body. Mirrors the web SDK's StickyActions.
+ *
+ * A step that carries a map or a street panorama fills a phone with a surface
+ * that OWNS every touch: dragging it moves the map, never the page, so on a
+ * small screen the Continue button beneath it could only be reached by finding
+ * a strip of margin to scroll on. Holding the actions under a bounded scroll
+ * view means the applicant never has to get past the map to move on, and
+ * everything else still scrolls under them.
+ *
+ * Needs a BOUNDED parent: the step must be listed in KycFlow's fillsViewport
+ * set, where the sheet hands it a flex:1 box padded `spacing.md`. The footer's
+ * negative margins cancel that padding so the bar meets the sheet's edge, and
+ * the same padding is restored inside so the buttons keep their gutter.
+ */
+export function StickyActions({
+  children,
+  actions,
+}: {
+  children: React.ReactNode;
+  actions: React.ReactNode;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View style={{ flex: 1 }}>
+      <ScrollView
+        style={{ flex: 1 }}
+        contentContainerStyle={{ paddingBottom: spacing.sm }}
+        keyboardShouldPersistTaps="handled"
+      >
+        {children}
+      </ScrollView>
+      <View
+        style={{
+          marginHorizontal: -spacing.md,
+          marginBottom: -spacing.md,
+          paddingHorizontal: spacing.md,
+          paddingTop: spacing.sm,
+          paddingBottom: spacing.md,
+          backgroundColor: colors.background,
+          borderTopWidth: StyleSheet.hairlineWidth,
+          borderTopColor: colors.border,
+        }}
+      >
+        {actions}
+      </View>
+    </View>
+  );
+}

package/src/components/dialCodeRows.ts

@@ -0,0 +1,64 @@
+import { groupCountriesByRegion, pinGeoRow } from '../config/regions';
+import type { DialCodeOption } from './DialCodePicker';
+
+// ---------------------------------------------------------------------------
+// What the country sheet lists, as data. Extracted from DialCodePicker
+// (200-line rule) so the FlatList only renders: the search, the pinned geo
+// row and the optional REGION grouping all decide here, and a unit test reads
+// the result without mounting a sheet. Grouping is what the address-scope
+// country control asks for (user decision 2026-09-06): its sheet reads like
+// the web's region menu and the country-select step — a continent header,
+// then its countries A–Z — rather than one 240-row alphabet. Mirrors
+// Flutter's dial_code_rows.dart.
+// ---------------------------------------------------------------------------
+
+export type DialCodeItem =
+  | { kind: 'row'; option: DialCodeOption }
+  | { kind: 'header'; region: string };
+
+/**
+ * Match the name, the ISO code, or the dial code with or without its '+',
+ * because people search for "+234", "234" and "Nigeria" in equal measure.
+ */
+export function filterDialCodeOptions(options: DialCodeOption[], query: string): DialCodeOption[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return options;
+  const bare = q.replace(/^\+/, '');
+  return options.filter(
+    (o) =>
+      o.name.toLowerCase().includes(q) ||
+      o.code.toLowerCase() === q ||
+      (o.dialCode != null && o.dialCode.replace(/^\+/, '').startsWith(bare)),
+  );
+}
+
+/**
+ * The sheet's items over the ALREADY-FILTERED options: where they appear to be
+ * first (lifted out of the alphabet, still subject to the search), then the
+ * rest — flat in the given order, or under region headers when `grouped`.
+ */
+export function buildDialCodeItems(
+  visible: DialCodeOption[],
+  geoCountry: string | null | undefined,
+  grouped: boolean,
+): { geo: DialCodeOption | null; items: DialCodeItem[] } {
+  const { pinned: geo, rest } = pinGeoRow(visible, geoCountry, (o) => o.code);
+  const items: DialCodeItem[] = geo ? [{ kind: 'row', option: geo }] : [];
+  if (!grouped) {
+    for (const option of rest) items.push({ kind: 'row', option });
+    return { geo, items };
+  }
+  const byCode = new Map(rest.map((o) => [o.code.toUpperCase(), o]));
+  for (const group of groupCountriesByRegion(rest.map((o) => o.code))) {
+    items.push({ kind: 'header', region: group.region });
+    for (const entry of group.countries) {
+      const option = byCode.get(entry.code);
+      if (option) items.push({ kind: 'row', option });
+    }
+  }
+  return { geo, items };
+}
+
+export function dialCodeItemKey(item: DialCodeItem): string {
+  return item.kind === 'header' ? `region:${item.region}` : item.option.code;
+}

package/src/components/documentReviewCopy.ts

@@ -0,0 +1,39 @@
+// ─── The review screen's words, per capture mode ──────────────────────────────
+//
+// The document review is shared by both ways a document gets in. "Retake" and
+// "captured" describe a camera, which an upload-only workflow
+// (`allowDocumentScan: false`) never shows the applicant, so that mode says
+// "Replace" and "added" instead, matching the web SDK. Scan mode (scan-only and
+// both-on) keeps its words exactly.
+//
+// Pure, so the wording is pinned by a test without mounting React Native.
+
+export type DocumentCaptureMode = 'scan' | 'upload';
+
+export interface DocumentReviewCopy {
+  /** The line above the thumbnails saying the capture is complete. */
+  status: string;
+  /** The labelled action under each thumbnail. */
+  redo: string;
+  /** The screen reader label for that action, naming the side. */
+  redoAccessibility: (sideLabel: string) => string;
+  /** The enlarged view's button, naming the side. */
+  redoSide: (sideLabel: string) => string;
+}
+
+export function documentReviewCopy(mode: DocumentCaptureMode, twoSided: boolean): DocumentReviewCopy {
+  if (mode === 'upload') {
+    return {
+      status: twoSided ? 'Both sides added' : 'Photo added',
+      redo: 'Replace',
+      redoAccessibility: (side) => `Replace the ${side.toLowerCase()} photo`,
+      redoSide: (side) => `Replace ${side.toLowerCase()}`,
+    };
+  }
+  return {
+    status: twoSided ? 'Both sides captured' : 'Photo captured',
+    redo: 'Retake',
+    redoAccessibility: (side) => `Retake ${side.toLowerCase()}`,
+    redoSide: (side) => `Retake ${side.toLowerCase()}`,
+  };
+}

package/src/components/fonts.ts

@@ -1,26 +1,29 @@
 import type { TextStyle } from 'react-native';
 import { useFonts } from 'expo-font';
-import { SpaceGrotesk_500Medium, SpaceGrotesk_600SemiBold, SpaceGrotesk_700Bold } from '@expo-google-fonts/space-grotesk';
-import { Karla_400Regular, Karla_500Medium, Karla_600SemiBold, Karla_700Bold } from '@expo-google-fonts/karla';
 import { fontFamilyFor } from '../config/font-resolve';
 import { useTheme } from './theme-provider';
 
 export { fontFamilyFor, markFamilyName, brandFamilyName, BRAND_WEIGHTS } from '../config/font-resolve';
 
-
 // Typography fonts — the SAME families the Flutter SDK uses via google_fonts:
 // Space Grotesk for headings, Karla for body. Loaded at runtime through
 // expo-font (already natively linked), so no native rebuild is needed. Each
 // weight is its own RN font family, so we resolve family-by-weight below.
-
+//
+// The files are VENDORED under src/assets/fonts and required one by one (see
+// the README there). They used to be named imports from the
+// @expo-google-fonts packages, whose index requires EVERY weight the family
+// ships — and Metro bundles every `require` it can see, used or not — so 19
+// font files reached every integrator's app for the seven faces the SDK draws
+// with. Measured at 1.85 MB on a real integrator's release APK.
 export const MYAZA_FONTS = {
-  SpaceGrotesk_500Medium,
-  SpaceGrotesk_600SemiBold,
-  SpaceGrotesk_700Bold,
-  Karla_400Regular,
-  Karla_500Medium,
-  Karla_600SemiBold,
-  Karla_700Bold,
+  SpaceGrotesk_500Medium: require('../assets/fonts/SpaceGrotesk_500Medium.ttf'),
+  SpaceGrotesk_600SemiBold: require('../assets/fonts/SpaceGrotesk_600SemiBold.ttf'),
+  SpaceGrotesk_700Bold: require('../assets/fonts/SpaceGrotesk_700Bold.ttf'),
+  Karla_400Regular: require('../assets/fonts/Karla_400Regular.ttf'),
+  Karla_500Medium: require('../assets/fonts/Karla_500Medium.ttf'),
+  Karla_600SemiBold: require('../assets/fonts/Karla_600SemiBold.ttf'),
+  Karla_700Bold: require('../assets/fonts/Karla_700Bold.ttf'),
 };
 
 /** Loads the Myaza fonts. Returns true once they're ready (system font until then). */
@@ -29,12 +32,6 @@ export function useMyazaFonts(): boolean {
   return loaded;
 }
 
-/**
- * Resolves the concrete RN font family for a (heading vs body, weight) pair.
- * Returns `undefined` until fonts are loaded so text falls back to the system
- * font + `fontWeight` without triggering an "unrecognized font" warning.
- */
-
 /**
  * The body font family for a TEXT INPUT, at the given weight.
  *