@myazahq/kyc-sdk-react-native 2.4.0 → 2.6.0

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,48 @@ 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.
   const headerCountry =
     currentStep === 'id-type' || currentStep === 'id-input' ? country : null;
-  const onBack = currentStep === 'consent' || currentStep === 'submitted' ? null : () => store.getState().previousStep();
+  // 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 +181,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>
+  );
+}

package/src/components/MapPinPicker.tsx

@@ -0,0 +1,179 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Image, PanResponder, View } from 'react-native';
+
+import { radius } from '../config/theme';
+import { useTheme } from './runtime';
+import { MapPinMarker } from './MapPinMarker';
+import { MapAttribution, MapZoomControls } from './MapChrome';
+import {
+  MAX_ZOOM,
+  MIN_ZOOM,
+  panCenter,
+  visibleTiles,
+  type LatLng,
+} from '../lib/map-tiles';
+
+interface MapPinPickerProps {
+  /** The confirmed pin, when one exists — the map centres on it. */
+  value: LatLng | null;
+  /** Fired when the user settles the map (drag end / zoom / recentre). */
+  onChange: (pin: LatLng) => void;
+  defaultCenter: LatLng;
+  defaultZoom: number;
+  /** Taller on the pin step, where there has to be room to actually find the
+   *  building; short on the review step's read-only summary. */
+  height?: number;
+  /**
+   * A read-only summary map: no gestures, no zoom controls, no onChange. The
+   * review step draws the pin as a picture of the decision, and a map that can
+   * be dragged there invites an edit the step is not offering.
+   */
+  interactive?: boolean;
+  /** Corner rounding — squared off when the map is clipped by a card. */
+  cornerRadius?: number;
+  /** Zoom when the map has a pin. The pin step goes closer than the default so
+   *  "is the pin on YOUR building?" is answerable without pinching first. */
+  pinZoom?: number;
+}
+
+const MAP_HEIGHT = 256;
+
+/**
+ * A dependency-free OSM slippy map with a FIXED CENTRE PIN — the user moves
+ * the map under the pin (the pattern address pickers use on phones), so the
+ * pin is always exactly the centre and there is no marker to fumble. Maths in
+ * lib/map-tiles.ts; this is only the gesture shell. Mirrors the web SDK's
+ * MapPinPicker: tiles for the committed centre, a live translate during the
+ * drag, and a commit (+ onChange) on release.
+ */
+export function MapPinPicker({
+  value,
+  onChange,
+  defaultCenter,
+  defaultZoom,
+  height = MAP_HEIGHT,
+  interactive = true,
+  cornerRadius,
+  pinZoom = 17,
+}: MapPinPickerProps) {
+  const { colors } = useTheme();
+  const [size, setSize] = useState<{ w: number; h: number } | null>(null);
+  const [center, setCenter] = useState<LatLng>(value ?? defaultCenter);
+  const [zoom, setZoom] = useState(value ? pinZoom : defaultZoom);
+  // Live drag offset — applied as a transform so panning stays smooth; the
+  // centre (and tile set) commits on release.
+  const [drag, setDrag] = useState<{ dx: number; dy: number } | null>(null);
+
+  // The responder callbacks close over state, so they read it via a ref — a
+  // PanResponder is created once and would otherwise pan against the centre
+  // and zoom from the first render forever.
+  const live = useRef({ center, zoom, onChange });
+  live.current = { center, zoom, onChange };
+
+  // An external recentre (a search pick, or Use my location) moves the map AND
+  // zooms in: "is the pin on your building?" cannot be answered at country
+  // zoom, and asking someone to pinch first is asking them to do our work.
+  // SELF-caused moves round-trip through the same prop (drag commits via
+  // onChange → store → new `value`), so a genuinely-external move is one that
+  // differs from the centre the map is already showing — without that check,
+  // an applicant who zoomed out to find their area was yanked back to pin
+  // zoom on every drag. Flutter's picker documents the same hazard.
+  useEffect(() => {
+    if (!value) return;
+    const c = live.current.center;
+    if (Math.abs(c.lat - value.lat) < 1e-9 && Math.abs(c.lng - value.lng) < 1e-9) return;
+    setCenter(value);
+    setZoom((z) => Math.max(z, pinZoom));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value?.lat, value?.lng]);
+
+  const pan = useRef(
+    PanResponder.create({
+      onStartShouldSetPanResponder: () => true,
+      onMoveShouldSetPanResponder: (_e, g) => Math.abs(g.dx) + Math.abs(g.dy) > 4,
+      onPanResponderMove: (_e, g) => setDrag({ dx: g.dx, dy: g.dy }),
+      onPanResponderRelease: (_e, g) => {
+        setDrag(null);
+        if (g.dx === 0 && g.dy === 0) return;
+        const { center: c, zoom: z, onChange: fire } = live.current;
+        const next = panCenter(c, z, g.dx, g.dy);
+        setCenter(next);
+        fire(next);
+      },
+      onPanResponderTerminate: () => setDrag(null),
+      // Android: a parent ScrollView (StickyActions) asks to take a vertical
+      // drag over once it passes the scroll slop; refuse, and block the native
+      // responder, or the map stops dead a few pixels in while the page moves.
+      onPanResponderTerminationRequest: () => false,
+      onShouldBlockNativeResponder: () => true,
+    }),
+  ).current;
+
+  const zoomBy = (delta: number) => {
+    const next = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, zoom + delta));
+    if (next === zoom) return;
+    setZoom(next);
+    onChange(center);
+  };
+
+  const tiles = size ? visibleTiles(center, zoom, size.w, size.h) : [];
+
+  return (
+    <View
+      accessibilityLabel={
+        interactive ? 'Map. Drag to position the pin on your address.' : 'Map showing your address'
+      }
+      onLayout={(e) =>
+        setSize({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height })
+      }
+      style={{
+        height,
+        borderRadius: cornerRadius ?? radius.md,
+        borderWidth: cornerRadius === 0 ? 0 : 1,
+        borderColor: colors.border,
+        backgroundColor: colors.backgroundSecondary,
+        overflow: 'hidden',
+      }}
+      {...(interactive ? pan.panHandlers : {})}
+    >
+      <View
+        style={{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+          transform: drag ? [{ translateX: drag.dx }, { translateY: drag.dy }] : [],
+        }}
+      >
+        {tiles.map((tile) => (
+          <Image
+            key={tile.key}
+            source={{ uri: tile.url }}
+            style={{ position: 'absolute', left: tile.left, top: tile.top, width: 256, height: 256 }}
+          />
+        ))}
+      </View>
+
+      {/* The fixed centre pin — its stem tip on the exact centre, lifted
+          with the landing dot beneath it while the map pans. */}
+      <View
+        pointerEvents="none"
+        style={{
+          position: 'absolute',
+          left: 0,
+          right: 0,
+          top: 0,
+          bottom: height / 2,
+          alignItems: 'center',
+          justifyContent: 'flex-end',
+        }}
+      >
+        <MapPinMarker lifted={drag != null} color={colors.primary} />
+      </View>
+
+      {interactive ? <MapZoomControls onZoom={zoomBy} /> : null}
+      <MapAttribution />
+    </View>
+  );
+}