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

package/src/components/Icon.tsx

@@ -1,192 +1,8 @@
 import React from 'react';
-import Ionicons from '@expo/vector-icons/Ionicons';
-import {
-  Info,
-  BadgeCheck,
-  BookUser,
-  Building2,
-  Calendar,
-  Camera,
-  CameraOff,
-  ChevronDown,
-  ChevronLeft,
-  ChevronRight,
-  Car,
-  Check,
-  CircleAlert,
-  Contact,
-  CreditCard,
-  Fingerprint,
-  FileText,
-  FlaskConical,
-  IdCard,
-  Image as ImageIcon,
-  Landmark,
-  Lightbulb,
-  Globe,
-  Mail,
-  Maximize2,
-  Lock,
-  MessageCircle,
-  MessageSquare,
-  Moon,
-  MoveLeft,
-  Nfc,
-  Filter,
-  Pencil,
-  Smartphone,
-  RefreshCw,
-  ScanFace,
-  ScanLine,
-  Search,
-  Zap,
-  ZapOff,
-  ShieldCheck,
-  Sun,
-  Timer,
-  Upload,
-  Plus,
-  UserRound,
-  UserRoundPlus,
-  Link2,
-  Copy,
-  Share2,
-  UsersRound,
-  VideoOff,
-  Vote,
-  X,
-  type LucideIcon,
-} from 'lucide-react-native';
 
-// Centralised icon set — the SAME Lucide icons the Flutter SDK uses
-// (`lucide_icons_flutter`) and the web SDK uses (`lucide-react`). Rendered via
-// lucide-react-native (react-native-svg), so the glyphs are pixel-identical
-// across all three platforms.
+import { ICONS, type IconName } from './icon-map';
 
-export type IconName =
-  // chrome
-  | 'close'
-  | 'back'
-  | 'moon'
-  | 'sun'
-  | 'check'
-  | 'lock'
-  | 'alert'
-  | 'flask'
-  | 'refresh'
-  | 'maximize'
-  | 'calendar'
-  | 'image'
-  | 'chevron-left'
-  | 'chevron-right'
-  | 'chevron-down'
-  // consent hero + process steps
-  | 'shield'
-  | 'badge-check'
-  | 'building-2'
-  | 'user'
-  | 'user-plus'
-  | 'plus'
-  | 'info'
-  | 'users'
-  | 'scan-line'
-  | 'scan-face'
-  | 'nfc'
-  | 'filter'
-  | 'pencil'
-  | 'search'
-  | 'zap'
-  | 'link'
-  | 'copy'
-  | 'share'
-  | 'zap-off'
-  | 'timer'
-  // id-type glyphs
-  | 'fingerprint'
-  | 'credit-card'
-  | 'globe'
-  | 'car'
-  | 'vote'
-  | 'file-text'
-  | 'landmark'
-  | 'id-card'
-  | 'contact'
-  | 'passport'
-  | 'camera'
-  | 'camera-off'
-  | 'video-off'
-  | 'upload'
-  | '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 ·
-//   creditCard · globe · car · vote · fileText  (+ chrome: X / ArrowLeft /
-//   Moon / Sun / Check / Lock / CircleAlert / RefreshCw / Camera).
-const ICONS: Record<IconName, LucideIcon> = {
-  close: X,
-  back: MoveLeft, // longer-shaft left arrow, matching Flutter's keyboard_backspace
-  moon: Moon,
-  sun: Sun,
-  check: Check,
-  lock: Lock,
-  alert: CircleAlert,
-  // The environment banner's mark, shared with the web SDK (same lucide glyph)
-  // and mirrored by Flutter's Icons.science_outlined.
-  flask: FlaskConical,
-  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,
-  info: Info,
-  'user-plus': UserRoundPlus,
-  plus: Plus,
-  link: Link2,
-  copy: Copy,
-  share: Share2,
-  users: UsersRound,
-  'scan-line': ScanLine,
-  'scan-face': ScanFace,
-  nfc: Nfc,
-  filter: Filter,
-  pencil: Pencil,
-  search: Search,
-  zap: Zap,
-  'zap-off': ZapOff,
-  timer: Timer,
-  fingerprint: Fingerprint,
-  'credit-card': CreditCard,
-  globe: Globe,
-  car: Car,
-  vote: Vote,
-  'file-text': FileText,
-  landmark: Landmark,
-  'id-card': IdCard,
-  contact: Contact,
-  passport: BookUser,
-  camera: Camera,
-  'camera-off': CameraOff,
-  'video-off': VideoOff,
-  upload: Upload,
-  x: X,
-  lightbulb: Lightbulb,
-  mail: Mail,
-  smartphone: Smartphone,
-  'message-square': MessageSquare,
-  'message-circle': MessageCircle,
-};
+export type { IconName } from './icon-map';
 
 export interface IconProps {
   name: IconName;
@@ -198,11 +14,13 @@ export interface IconProps {
 }
 
 export function Icon({ name, size = 20, color, strokeWidth = 2, solid = false }: IconProps): React.ReactElement {
-  // Solid moon/sun for the theme toggle — Lucide has no filled variants, so use
-  // Ionicons' purpose-built solid glyphs (matches Flutter's dark_mode/light_mode).
-  if (solid && (name === 'moon' || name === 'sun')) {
-    return <Ionicons name={name === 'moon' ? 'moon' : 'sunny'} size={size} color={color} />;
-  }
   const Glyph = ICONS[name];
-  return <Glyph size={size} color={color} strokeWidth={strokeWidth} />;
+  // The theme toggle's filled moon/sun (Flutter's dark_mode/light_mode). Lucide
+  // ships no filled variants, so the glyph's own body takes the colour: the
+  // moon's crescent and the sun's disc fill, the sun's rays stay strokes. This
+  // replaced an Ionicons import that was the SDK's ONLY use of
+  // @expo/vector-icons, a package whose icon fonts still reached every
+  // integrator's app for those two glyphs (1.35 MB on a real release APK).
+  const fill = solid && (name === 'moon' || name === 'sun') ? color : 'none';
+  return <Glyph size={size} color={color} strokeWidth={strokeWidth} fill={fill} />;
 }

package/src/components/KycFlow.tsx

@@ -3,6 +3,7 @@ import { View } from 'react-native';
 
 import { radius, spacing } from '../config/theme';
 import { buildStepOrder } from '../config/stepOrder';
+import { isAddressStep } from '../lib/address-flow';
 import { stepOrderOptions } from '../store/kycStore';
 import { KYCError } from '../types/verification';
 import { safeReportError } from '../services/errors';
@@ -50,6 +51,7 @@ export function KycFlow({
   const contactChallenge = useKyc((s) => s.contactChallenge);
   const serverConfig = useKyc((s) => s.serverConfig);
   const immersiveCapture = useKyc((s) => s.immersiveCapture);
+  const addressIntroSeen = useKyc((s) => s.addressIntroSeen);
 
   const startedRef = useRef(false);
   const reportedRef = useRef(false);
@@ -76,7 +78,26 @@ export function KycFlow({
     }
   }, [isFatal, serverConfig.statusCode, serverConfig.message, config.onError]);
 
-  // ── Per-step header meta ──────────────────────────────────────────────────
+  // ── The flow's ordered steps ──────────────────────────────────────────────
+  // ONE list, read by the step indicator AND by the address primer below, so
+  // neither can describe a flow the user is not walking. This used to be a
+  // hand-written copy of the sequence, which meant a step added to the flow
+  // silently didn't count towards progress.
+  //
+  // 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 order = useMemo(() => buildStepOrder(stepOrderOptions(state)), [state]);
+
+  // The presence primer replaces the FIRST address step's body and carries its
+  // own title, so the header blanks while it is up. Matched against the order
+  // rather than a second copy of "which step comes first".
+  const addressIntroPending =
+    config.addressCollection?.presence?.enabled === true &&
+    !addressIntroSeen &&
+    order.find(isAddressStep) === currentStep;
+
   const meta = useMemo(
     () =>
       stepHeaderMeta(currentStep, {
@@ -85,40 +106,55 @@ export function KycFlow({
         selectedIdType,
         documentCapturePhase,
         contactChallenge,
+        addressIntroPending,
+        addressEntranceFraming: state.addressEntranceFraming,
+        poaDocumentType: state.poaDocumentType,
       }),
-    [currentStep, config, country, selectedIdType, documentCapturePhase, contactChallenge],
+    [
+      currentStep,
+      config,
+      country,
+      selectedIdType,
+      documentCapturePhase,
+      contactChallenge,
+      addressIntroPending,
+      state.addressEntranceFraming,
+      state.poaDocumentType,
+    ],
   );
 
   // ── 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 (state.currentStep === 'submitted') return null;
-    const steps = buildStepOrder(stepOrderOptions(state)).filter((s) => s !== 'submitted');
-    const idx = steps.indexOf(state.currentStep);
+    if (currentStep === 'submitted') return null;
+    const steps = order.filter((s) => s !== 'submitted');
+    const idx = steps.indexOf(currentStep);
     if (idx < 0) return null;
     return { progress: (idx + 1) / steps.length, stepCount: steps.length };
-  }, [state]);
+  }, [currentStep, order]);
 
-  // The flag beside the title names the country whose IDs are on screen.
+  // The flag beside the title names the country whose IDs are on screen. The
+  // document steps ask for a country's document just as directly as the ID
+  // ones do, so they carry the same flag rather than a second treatment.
   const headerCountry =
-    currentStep === 'id-type' || currentStep === 'id-input' ? country : null;
-  const onBack = currentStep === 'consent' || currentStep === 'submitted' ? null : () => store.getState().previousStep();
+    currentStep === 'id-type' ||
+    currentStep === 'id-input' ||
+    currentStep === 'document-capture' ||
+    currentStep === 'nfc'
+      ? country
+      : null;
+  // Back is hidden on the flow's OPENING step (consent, or the first real step
+  // when the workflow switched the consent screen off), not on consent by
+  // name. A multi-ID run returns to the ID picker for its next check, where
+  // Back means "redo the previous one", so a committed slot keeps it.
+  const onOpeningStep = currentStep === order[0] && state.multiIdSlots.length === 0;
+  const onBack = onOpeningStep || currentStep === 'submitted' ? null : () => store.getState().previousStep();
 
   // Android hardware back arrives via the <Modal>'s onRequestClose. Expose a
   // back-aware handler through `backRef` so that handler navigates a step back
   // when the flow can, instead of dismissing the whole SDK. It only reports
-  // 'close' from the first step (consent) with close allowed; with
+  // 'close' from the opening step with close allowed; with
   // `disableClose` set it reports 'blocked' so back can never force the flow
   // closed. (iOS has no hardware back; its swipe-down keeps the standard
   // dismiss behaviour, handled by the Modal.)
@@ -152,22 +188,21 @@ export function KycFlow({
         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.
+        // The searchable country picker (>5 countries) pins its search box
+        // above a ~240-row list; the address pin and entrance steps fill it
+        // too, since a map or panorama owns every touch and their actions
+        // ride StickyActions at the bottom of a BOUNDED body.
         fillsViewport={
-          currentStep === 'country-select' &&
-          countrySelectOptions({ config, serverConfig }).length > COUNTRY_SEARCH_THRESHOLD
+          (currentStep === 'country-select' &&
+            countrySelectOptions({ config, serverConfig }).length > COUNTRY_SEARCH_THRESHOLD) ||
+          currentStep === 'address-collection' ||
+          currentStep === 'address-entrance'
         }
-        // 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.
+        // A live camera asks for the whole screen (a camera you have to scroll
+        // to is a broken camera). Passed as a PROP rather than rendered as its
+        // own tree: an early-returned tree changed the step's parent MID-STEP,
+        // so React remounted it and wiped the acknowledged primer. 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} />

package/src/components/LineSkeleton.tsx

@@ -0,0 +1,100 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, View } from 'react-native';
+
+import { radius } from '../config/theme';
+import { useTheme } from './runtime';
+import { MyazaText } from './Typography';
+import { useReduceMotion } from './StaggerIn';
+
+// ─── A text line that is on its way ─────────────────────────────────────────
+//
+// Drawn at the line's own height so the card around it does not move when the
+// words land, and shaped like the answer (a rounded bar about the width of a
+// short address) rather than a spinner: a spinner beside grey text says
+// "busy", a bar where the text goes says "the line is coming" (user decision
+// 2026-09-07). The pin summary and the review card use it while the reverse
+// geocode is out. It pulses the way KeyPeoplePending's ghost roster does, so
+// the SDK has one skeleton language, and holds still under reduced motion.
+// The words still reach assistive tech through the live-region label.
+//
+// Mirrors the web SDK's components/LineSkeleton and Flutter's
+// widgets/line_skeleton.dart.
+
+type Variant = React.ComponentProps<typeof MyazaText>['variant'];
+
+export function LineSkeleton({
+  label,
+  variant = 'bodyMedium',
+  textStyle,
+  barHeight = 10,
+  width = '62%',
+  style,
+}: {
+  /** What a screen reader hears, e.g. "Finding the address…". */
+  label: string;
+  /** The variant the real line renders with, so the ghost owns its height. */
+  variant?: Variant;
+  textStyle?: object;
+  barHeight?: number;
+  /** How much of the line the bar covers; an address, not a paragraph. */
+  width?: number | `${number}%`;
+  style?: object;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const reduceMotion = useReduceMotion();
+  const pulse = useRef(new Animated.Value(1)).current;
+
+  useEffect(() => {
+    if (reduceMotion) return undefined;
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, { toValue: 0.45, duration: 600, useNativeDriver: true }),
+        Animated.timing(pulse, { toValue: 1, duration: 600, useNativeDriver: true }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [pulse, reduceMotion]);
+
+  return (
+    <View
+      accessible
+      accessibilityLiveRegion="polite"
+      accessibilityLabel={label}
+      style={[{ justifyContent: 'center' }, style]}
+    >
+      {/* An invisible line in the real variant owns the height, so the card
+          does not move when the words replace the bar. */}
+      <MyazaText variant={variant} style={[textStyle, { opacity: 0 }]} numberOfLines={1}>
+        {' '}
+      </MyazaText>
+      <Animated.View
+        pointerEvents="none"
+        style={{
+          position: 'absolute',
+          left: 0,
+          width,
+          height: barHeight,
+          borderRadius: radius.full,
+          backgroundColor: colors.primary100,
+          opacity: reduceMotion ? 0.7 : pulse,
+        }}
+      />
+    </View>
+  );
+}
+
+/** The resolved line fading in where the skeleton was, so the swap reads as
+ *  the answer landing rather than a flicker. Instant under reduced motion. */
+export function LineReveal({ children, style }: { children: React.ReactNode; style?: object }): React.ReactElement {
+  const reduceMotion = useReduceMotion();
+  const opacity = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    if (reduceMotion) {
+      opacity.setValue(1);
+      return;
+    }
+    Animated.timing(opacity, { toValue: 1, duration: 200, useNativeDriver: true }).start();
+  }, [opacity, reduceMotion]);
+  return <Animated.View style={[{ opacity }, style]}>{children}</Animated.View>;
+}

package/src/components/MapChrome.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { Pressable, View } from 'react-native';
+
+import { radius } from '../config/theme';
+import { useTheme } from './runtime';
+import { Icon } from './Icon';
+import { MyazaText } from './Typography';
+
+// The map's furniture, split from MapPinPicker per the 200-line rule.
+
+/** Zoom controls, top-right. Absent on a read-only summary map. */
+export function MapZoomControls({ onZoom }: { onZoom: (delta: number) => void }): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        position: 'absolute',
+        right: 8,
+        top: 8,
+        borderRadius: radius.sm,
+        borderWidth: 1,
+        borderColor: colors.border,
+        backgroundColor: colors.background,
+        overflow: 'hidden',
+      }}
+    >
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel="Zoom in"
+        onPress={() => onZoom(1)}
+        style={{ padding: 8 }}
+      >
+        <Icon name="plus" size={16} color={colors.textDark} />
+      </Pressable>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel="Zoom out"
+        onPress={() => onZoom(-1)}
+        style={{ padding: 8, borderTopWidth: 1, borderTopColor: colors.border }}
+      >
+        <Icon name="minus" size={16} color={colors.textDark} />
+      </Pressable>
+    </View>
+  );
+}
+
+/** OSM tile-usage terms require this to be visible wherever the tiles are. */
+export function MapAttribution(): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      pointerEvents="none"
+      style={{
+        position: 'absolute',
+        right: 6,
+        bottom: 4,
+        paddingHorizontal: 4,
+        borderRadius: 3,
+        backgroundColor: colors.background + 'B3',
+      }}
+    >
+      <MyazaText variant="bodySmall" style={{ fontSize: 10 }} color={colors.textSecondary}>
+        © OpenStreetMap contributors
+      </MyazaText>
+    </View>
+  );
+}

package/src/components/MapPinMarker.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { View } from 'react-native';
+import Svg, { Circle, Rect } from 'react-native-svg';
+
+// ---------------------------------------------------------------------------
+// The Myaza map pin — the same drawing as the web SDK's MapPinMarker and
+// Flutter's map_pin_marker.dart, so the built-in OSM picker wears the pin the
+// framed Google map already does. A 1:1 copy of the Bolt reference: head 46px,
+// eye 0.31, stem 0.098 wide showing 0.41 below the head, no casings, flat body
+// (no shadow on the pin itself).
+//
+// The GROUND DOT is the drag-state shadow: while the map pans the pin lifts
+// 17px and the dot appears at the landing point beneath it; when the pin
+// lands the dot goes, leaving the stem tip resting exactly on the picked
+// coordinate. The parent aligns this widget's BOTTOM edge to the map centre.
+// ---------------------------------------------------------------------------
+
+export const PIN_LIFT = 17;
+
+export function MapPinMarker({
+  lifted,
+  color,
+}: {
+  /** The map is mid-pan: the pin floats and the landing dot shows. */
+  lifted: boolean;
+  /** The workflow's primary colour (the whole pin wears it). */
+  color: string;
+}): React.ReactElement {
+  return (
+    <View style={{ alignItems: 'center' }} pointerEvents="none">
+      <View
+        style={{
+          position: 'absolute',
+          bottom: -2.5,
+          width: 11,
+          height: 5,
+          borderRadius: 3,
+          backgroundColor: 'rgba(7, 3, 48, 0.5)',
+          opacity: lifted ? 1 : 0,
+        }}
+      />
+      <Svg
+        width={46}
+        height={65}
+        viewBox="0 0 46 65"
+        style={{ transform: [{ translateY: lifted ? -PIN_LIFT : 0 }] }}
+      >
+        <Rect x={20.75} y={42} width={4.5} height={23} rx={2.25} fill={color} />
+        <Circle cx={23} cy={23} r={23} fill={color} />
+        <Circle cx={23} cy={23} r={7} fill="#FFFFFF" />
+      </Svg>
+    </View>
+  );
+}