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

package/src/screens/address/AddressIntroGate.tsx

@@ -0,0 +1,148 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useKyc, useKycConfig, useKycStore, useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { MyazaButton } from '../../components/MyazaButton';
+import { Icon } from '../../components/Icon';
+import { MilestoneTrack, type Milestone } from '../../components/MilestoneTrack';
+import { IntroDisclosures } from './IntroDisclosures';
+import type { KYCStep } from '../../types/config';
+
+// ---------------------------------------------------------------------------
+// The presence "how it works" screen, shown ONCE before the address flow's
+// first step. Drawn in the SUCCESS CARD's language — eyebrow pill, header band,
+// milestone track — so the promise made here and the "address check active"
+// card at the end read as two frames of one story.
+//
+// The underlying step still does its mount work behind this gate: the
+// current-fix prefetch starts while the primer is on screen, so by the time
+// "Got it" is tapped the fix is usually already in hand and the pin lands with
+// no hesitation. Only the APPLY waits.
+// ---------------------------------------------------------------------------
+
+// The second milestone's caption depends on which tier the org runs. With
+// background geofencing on, the "allow all the time" prompt is coming, and
+// OkHi's integration guidance is to say so ONCE, up front, beside the
+// education — not to surprise the person with it after capture.
+const CHECK_IN_CAPTION = {
+  foreground: 'Keep location on; your phone confirms it over the coming days.',
+  background:
+    'Allow location all the time when asked. Your phone then confirms it on its own, even with the app closed.',
+} as const;
+
+const milestonesFor = (background: boolean): readonly Milestone[] => [
+  {
+    icon: 'map-pin-house',
+    stage: 'Your part',
+    title: 'Pin your address',
+    caption: 'Put the pin right on your building. Takes a minute.',
+    state: 'active',
+  },
+  {
+    icon: 'radar',
+    stage: 'After that',
+    title: 'Quiet check-ins',
+    caption: background ? CHECK_IN_CAPTION.background : CHECK_IN_CAPTION.foreground,
+    state: 'ahead',
+  },
+  {
+    icon: 'bell-ring',
+    stage: 'Then',
+    title: 'Confirmed',
+    caption: 'You’ll be notified. That is it.',
+    state: 'ahead',
+  },
+];
+
+/**
+ * The gate for `step`, or null when it should not show. Returning the element
+ * (rather than a boolean) keeps the decision and the screen in one place: a
+ * step renders `gate ?? its own body`.
+ */
+export function useAddressIntroGate(
+  step: KYCStep,
+  firstStep: KYCStep,
+): React.ReactElement | null {
+  const config = useKycConfig();
+  const store = useKycStore();
+  const { colors } = useTheme();
+  const seen = useKyc((s) => s.addressIntroSeen);
+  const presence = config.addressCollection?.presence?.enabled === true;
+  const background = config.addressCollection?.presence?.background === true;
+
+  if (step !== firstStep || !presence || seen) return null;
+
+  return (
+    <View>
+      {/* Web's exact tints (border-primary/15, bg-primary/[0.06], the badge
+          on primary/10), as hex alpha on the primary so a custom brand and
+          dark mode both keep the relationship; Flutter draws the same. */}
+      <View
+        style={{
+          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`,
+            }}
+          >
+            <Icon name="map-pin-check" size={12} color={colors.primary} />
+            <MyazaText
+              variant="bodySmall"
+              color={colors.primary}
+              style={{
+                fontSize: 11,
+                fontWeight: '600',
+                letterSpacing: 0.6,
+                textTransform: 'uppercase',
+              }}
+            >
+              Address verification
+            </MyazaText>
+          </View>
+          {/* Web's `text-base font-semibold`: the BODY face at 16/600, not a
+              heading, so it matches the review card's address line. */}
+          <MyazaText variant="body" style={{ marginTop: spacing.sm, fontWeight: '600' }}>
+            Let’s confirm your address
+          </MyazaText>
+          <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ marginTop: 2 }}>
+            This address will be verified over the coming days. Your part takes a minute; the rest
+            happens on its own.
+          </MyazaText>
+        </View>
+
+        <MilestoneTrack milestones={milestonesFor(background)} numbered />
+      </View>
+
+      <View style={{ height: spacing.md }} />
+      <IntroDisclosures background={background} />
+
+      <View style={{ height: spacing.lg }} />
+      <MyazaButton
+        label="Got it, let’s go"
+        onPress={() => store.getState().markAddressIntroSeen()}
+      />
+    </View>
+  );
+}

package/src/screens/address/AddressMapStub.tsx

@@ -0,0 +1,50 @@
+import React, { useEffect } from 'react';
+import { View } from 'react-native';
+
+import { MyazaText } from '../../components/Typography';
+import { Icon } from '../../components/Icon';
+import { DashedBorder } from '../../components/DashedBorder';
+import { useTheme } from '../../components/runtime';
+import { spacing } from '../../config/theme';
+import type { LatLng } from '../../lib/map-tiles';
+
+// The SANDBOX map stand-in (the web SDK's preview placeholder, for test
+// keys): no tiles, no framed page, no vendor loads. The pin lands on the
+// default centre once — what the real map's first idle emits — so Continue
+// stays reachable and the integrator walks the whole flow.
+export function AddressMapStub({
+  hasPin,
+  onLand,
+  defaultCenter,
+  height,
+}: {
+  hasPin: boolean;
+  onLand: (pin: LatLng) => void;
+  defaultCenter: LatLng;
+  height: number;
+}) {
+  useEffect(() => {
+    if (!hasPin) onLand(defaultCenter);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hasPin]);
+
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        height,
+        borderRadius: 12,
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: spacing.lg,
+      }}
+    >
+      <DashedBorder color={colors.border} radius={12} strokeWidth={1} />
+      <Icon name="map-pin-house" size={32} color={colors.textSecondary} />
+      <View style={{ height: spacing.sm }} />
+      <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ textAlign: 'center' }}>
+        Applicants place their pin on a live map here. The map loads only for real users.
+      </MyazaText>
+    </View>
+  );
+}

package/src/screens/address/AddressPinStep.tsx

@@ -0,0 +1,178 @@
+import React, { useEffect, useState } from 'react';
+import { useWindowDimensions, View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useKyc, useKycStore, useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { MyazaButton } from '../../components/MyazaButton';
+import { FramedMapPicker } from '../../components/FramedMapPicker';
+import { StickyActions } from '../../components/StickyActions';
+import { displayAddressLine, shouldAskLabelDecision, addressVendorsStubbed } from '../../lib/address-flow';
+import { missingFieldsNudge, missingRequiredAddressFields } from '../../lib/address-field-modes';
+import { claimAutoLocate } from '../../lib/address-current-location';
+import { mapSurfaceHeight } from '../../lib/map-tiles';
+import { useAddressFlow } from './use-address-flow';
+import { AddressMapStub } from './AddressMapStub';
+import { useAddressIntroGate } from './AddressIntroGate';
+import { CurrentLocationRow, LocateChip } from './CurrentLocationRow';
+import { LabelDecisionRow } from './LabelDecisionRow';
+import { DetailsSheet } from './DetailsSheet';
+import { detailValuesOf } from './detail-values';
+import { PinSummaryRow } from './PinSummaryRow';
+import { SkipForNow } from './SkipForNow';
+
+/**
+ * The PIN step (wire name 'address-collection', kept so older session progress
+ * restores cleanly and the server's step-log titles stay meaningful).
+ *
+ * A big map — sized by mapSurfaceHeight, so a phone keeps room to scroll —
+ * with the summary row and the details sheet beneath it, and Continue held at
+ * the bottom edge (StickyActions) so the map can never put it out of reach.
+ * On KYB this is the WHOLE premises capture, so Continue commits (attest fix
+ * included); on an individual flow it advances to the entrance and review
+ * steps. Workflow-required details hold Continue and open the sheet on the
+ * missing fields rather than pointing at a closed drawer.
+ */
+export function AddressPinStep(): React.ReactElement {
+  const store = useKycStore();
+  const { colors } = useTheme();
+  const viewport = useWindowDimensions();
+  const flow = useAddressFlow();
+  // The framed Google picker when the platform serves one; the OSM picker
+  // otherwise (and whenever the page never says ready).
+  const mapsFrameUrl = useKyc((s) => s.serverConfig.mapsFrameUrl ?? null);
+  // SANDBOX renders the stand-in (the web SDK's vendor-stub rule): verdicts
+  // are canned server-side, so a live map on a test key only spends quota.
+  const vendorsStubbed = addressVendorsStubbed({
+    environment: useKyc((s) => s.serverConfig.environment ?? null),
+  });
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const [missingNudge, setMissingNudge] = useState(false);
+  const gate = useAddressIntroGate('address-collection', flow.steps[0]!);
+
+  const gateShowing = Boolean(gate);
+  const noPin = !flow.pin;
+  const { startPrefetch, relabelPin, applyCurrentFix } = flow;
+  useEffect(() => {
+    // The fix warms even under the primer: only the APPLY waits for it, since
+    // a pin landing behind the gate would be invisible anyway.
+    startPrefetch();
+    if (gateShowing) return;
+    // A restored pin without its line (a snapshot saved before labels existed):
+    // reverse-geocode it once rather than showing raw coordinates.
+    relabelPin();
+    // Most people are verifying from home, so the map should land on them
+    // rather than a country-centre default. Silent by contract, and claimed
+    // once per verification: a dismissed or denied prompt must not re-fire
+    // every time the person passes back through this step.
+    if (!noPin || !claimAutoLocate()) return;
+    void applyCurrentFix(undefined, { silent: true });
+  }, [gateShowing, noPin, startPrefetch, relabelPin, applyCurrentFix]);
+
+  if (gate) return gate;
+
+
+
+  const address = flow.address;
+  const label = address?.label ?? null;
+  const askLabel = address ? shouldAskLabelDecision(address) : false;
+  // The pin step is the last of the flow on KYB, so its Continue commits.
+  const lastInFlow = flow.isBusiness;
+  const mapHeight = mapSurfaceHeight(viewport);
+
+  const missingRequired = missingRequiredAddressFields(flow.cfg, address);
+  const handleContinue = () => {
+    if (missingRequired.length > 0) {
+      setMissingNudge(true);
+      setSheetOpen(true);
+      return;
+    }
+    if (lastInFlow) void flow.confirm();
+    else flow.goNext();
+  };
+
+  return (
+    <>
+      <StickyActions
+        actions={
+          <>
+            <MyazaButton
+              label="Continue"
+              loading={flow.confirming}
+              disabled={!flow.pin}
+              onPress={handleContinue}
+            />
+            <SkipForNow requirePin={flow.cfg?.requirePin} onPress={flow.exitForward} />
+          </>
+        }
+      >
+        <View>
+          {vendorsStubbed ? (
+            <AddressMapStub hasPin={Boolean(flow.pin)} onLand={(next) => flow.setPin(next)} defaultCenter={flow.view.center} height={mapHeight} />
+          ) : (
+            <FramedMapPicker
+              frameUrl={mapsFrameUrl}
+              value={flow.pin}
+              onChange={(next) => flow.setPin(next)}
+              defaultCenter={flow.view.center}
+              defaultZoom={flow.view.zoom}
+              height={mapHeight}
+            />
+          )}
+          {flow.pin ? <LocateChip locating={flow.locating} onPress={() => void flow.locateToPin()} /> : null}
+        </View>
+
+        <View style={{ height: spacing.md }} />
+        <PinSummaryRow
+          line={address ? displayAddressLine(address) : null}
+          labelling={flow.labelling}
+          values={detailValuesOf(address)}
+          disabled={!flow.pin}
+          onPress={() => setSheetOpen(true)}
+        />
+
+        {askLabel && label ? (
+          <>
+            <View style={{ height: spacing.md }} />
+            <LabelDecisionRow label={label} onKeep={flow.keepPickedLabel} onAdopt={flow.adoptPinAddress} />
+          </>
+        ) : null}
+
+        {flow.pin ? null : (
+          <>
+            <View style={{ height: spacing.md }} />
+            <CurrentLocationRow hint={flow.currentFix?.label ?? null} locating={flow.locating} onPress={() => void flow.applyCurrentFix()} />
+          </>
+        )}
+
+        {flow.error ? (
+          <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.sm }}>
+            {flow.error}
+          </MyazaText>
+        ) : null}
+        {missingNudge && missingRequired.length > 0 ? (
+          <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.sm }}>
+            {missingFieldsNudge(missingRequired)}
+          </MyazaText>
+        ) : null}
+      </StickyActions>
+
+      {sheetOpen ? (
+        <DetailsSheet
+          isBusiness={flow.isBusiness}
+          parts={address?.parts ?? null}
+          country={flow.country ?? null}
+          directionsRequired={flow.cfg?.directions === 'required'}
+          addressConfig={flow.cfg}
+          values={detailValuesOf(address)}
+          disabled={!flow.pin}
+          onChange={(patch) => {
+            const current = store.getState().address;
+            if (current) store.getState().setAddress({ ...current, ...patch });
+          }}
+          onClose={() => setSheetOpen(false)}
+        />
+      ) : null}
+    </>
+  );
+}

package/src/screens/address/AddressReviewStep.tsx

@@ -0,0 +1,162 @@
+import React, { useEffect, useState } from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useKyc, useKycStore, useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { MyazaButton } from '../../components/MyazaButton';
+import { displayAddressLine, addressVendorsStubbed } from '../../lib/address-flow';
+import { useAuthedImage } from '../../lib/authed-image';
+import { missingFieldsNudge, missingRequiredAddressFields } from '../../lib/address-field-modes';
+import { useAddressFlow } from './use-address-flow';
+import { AddressSandboxTabs } from './AddressSandboxTabs';
+import { SkipForNow } from './SkipForNow';
+import { ReviewMapPicture } from './ReviewMapPicture';
+import { HERO, SECOND, ReviewEntranceThumb } from './ReviewEntranceThumbs';
+import { ReviewAddressBand } from './ReviewAddressBand';
+
+/**
+ * The commit point, as ONE composed card: a read-only summary map with the
+ * entrance photo hanging over its bottom edge like a photo clipped to a
+ * document, and the address underneath as the card's own heading. Tapping the
+ * map jumps back to the pin step. The presence story lives on the intro
+ * screen, not here. Workflow-required details the applicant skipped hold
+ * Confirm (the pin step's own gate, repeated here as the backstop). The map
+ * surface is ReviewMapPicture, the thumbnails ReviewEntranceThumbs.
+ */
+export function AddressReviewStep(): React.ReactElement {
+  const store = useKycStore();
+  const { colors } = useTheme();
+  const flow = useAddressFlow();
+  const previewUri = useKyc((s) => s.addressPhotoPreview);
+  const mapsFrameUrl = useKyc((s) => s.serverConfig.mapsFrameUrl ?? null);
+  const vendorsStubbed = addressVendorsStubbed({
+    environment: useKyc((s) => s.serverConfig.environment ?? null),
+  });
+
+  // A resumed session can land straight here with a pin that predates the
+  // label fields — reverse-geocode it once rather than showing coordinates.
+  const { relabelPin } = flow;
+  useEffect(() => {
+    relabelPin();
+  }, [relabelPin]);
+
+  const address = flow.address;
+  const directions = address?.directions.trim() || null;
+
+  // The framed Street View entrance, drawn through the server: the browser
+  // key lives in the framed page, never in this SDK. Fetched with the SDK's
+  // bearer by lib/authed-image (an <Image> header is dropped on Android).
+  const frame = address?.streetView ?? null;
+  const api = useKyc((s) => s.api);
+  const frameImage = useAuthedImage(frame ? api.streetViewPreviewSource(frame) : null, 'Street View entrance');
+  const frameSource = frameImage.uri ? { uri: frameImage.uri } : null;
+  // The map as a picture, through the same bearer; a refused one (the Static
+  // API is a separate console enablement) falls back to the live map.
+  const mapImage = useAuthedImage(
+    flow.pin && !vendorsStubbed ? api.staticMapSource({ ...flow.pin, zoom: 16 }) : null,
+    'Map picture',
+  );
+  const [pictureFailed, setPictureFailed] = useState(false);
+  // An entrance thumbnail whose bytes never arrive must not stay on screen as
+  // an empty bordered box hanging over the map (the S24, 2026-09-07); it drops
+  // out, and the band's clearance with it.
+  const [heroFailed, setHeroFailed] = useState(false);
+  const [secondFailed, setSecondFailed] = useState(false);
+  const failed = (label: string, error: unknown): void => {
+    if (__DEV__) console.warn(`${label} failed to load`, error);
+  };
+
+  // The photo leads when there is one, exactly as on web; the framed view
+  // takes the smaller slot beside it, or the big one when it is all there is.
+  const hero = previewUri ? { uri: previewUri } : frameSource;
+  const second = previewUri && frameSource ? frameSource : null;
+  const heroLabel = previewUri ? 'Entrance photo' : 'Street View entrance';
+  const heroShown = hero && !heroFailed ? hero : null;
+  const secondShown = second && !secondFailed ? second : null;
+  const missingRequired = missingRequiredAddressFields(flow.cfg, address);
+  const toPin = (): void => store.getState().goToStep('address-collection');
+  const line = address ? displayAddressLine(address) : '';
+
+  return (
+    <View>
+      <View style={{ borderWidth: 1, borderColor: colors.border, borderRadius: radius.md }}>
+        {flow.pin ? (
+          // ABOVE the band, which paints a solid background: without this the
+          // entrance hanging over the map's edge was covered by it.
+          <View style={{ zIndex: 2 }}>
+            <ReviewMapPicture
+              pin={flow.pin}
+              vendorsStubbed={vendorsStubbed}
+              mapsFrameUrl={mapsFrameUrl}
+              staticMap={mapImage.uri ? { uri: mapImage.uri } : null}
+              staticMapFailed={mapImage.failed || pictureFailed}
+              onEdit={toPin}
+              onPictureFailed={() => setPictureFailed(true)}
+            />
+            {heroShown ? (
+              <ReviewEntranceThumb
+                source={heroShown}
+                label={heroLabel}
+                size={HERO}
+                right={16}
+                onFailed={(e) => {
+                  failed(heroLabel, e);
+                  setHeroFailed(true);
+                }}
+              />
+            ) : null}
+            {secondShown ? (
+              <ReviewEntranceThumb
+                source={secondShown}
+                label="Street View entrance"
+                size={SECOND}
+                right={144}
+                onFailed={(e) => {
+                  failed('Street View entrance', e);
+                  setSecondFailed(true);
+                }}
+              />
+            ) : null}
+          </View>
+        ) : null}
+
+        <ReviewAddressBand
+          isBusiness={flow.isBusiness}
+          hasAddress={Boolean(address)}
+          line={line}
+          labelling={flow.labelling}
+          directions={directions}
+          clearsHero={Boolean(heroShown)}
+          onEdit={toPin}
+        />
+      </View>
+
+      {flow.error ? (
+        <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.sm }}>
+          {flow.error}
+        </MyazaText>
+      ) : null}
+      {missingRequired.length > 0 ? (
+        <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.sm }}>
+          {`${missingFieldsNudge(missingRequired)} `}
+          <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600' }} onPress={toPin}>
+            Edit details
+          </MyazaText>
+        </MyazaText>
+      ) : null}
+
+      <View style={{ height: spacing.lg }} />
+      <AddressSandboxTabs />
+      <View style={{ height: spacing.md }} />
+      <MyazaButton
+        label="Confirm address"
+        loading={flow.confirming}
+        disabled={!flow.pin || missingRequired.length > 0}
+        onPress={() => void flow.confirm()}
+      />
+
+      <SkipForNow requirePin={flow.cfg?.requirePin} onPress={flow.exitForward} />
+    </View>
+  );
+}