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

package/src/screens/address/ReviewMapPicture.tsx

@@ -0,0 +1,106 @@
+import React from 'react';
+import { Image, Pressable, View } from 'react-native';
+
+import { radius } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MapPinPicker } from '../../components/MapPinPicker';
+import { FramedMapPicker } from '../../components/FramedMapPicker';
+import { MapPinMarker } from '../../components/MapPinMarker';
+import { reviewMapSurface } from '../../lib/review-map-surface';
+import type { LatLng } from '../../lib/map-tiles';
+import { AddressMapStub } from './AddressMapStub';
+
+// The review card's map (200-line split from AddressReviewStep). The map as a
+// PICTURE: a confirmation screen wants a photograph of the place, not a second
+// instrument. Which surface draws is lib/review-map-surface.ts, the order the
+// web and Flutter cards keep.
+
+// Web's review map is h-48 (192px) at mobile widths; keep the mirror exact.
+export const REVIEW_MAP_HEIGHT = 192;
+
+export function ReviewMapPicture({
+  pin,
+  vendorsStubbed,
+  mapsFrameUrl,
+  staticMap,
+  staticMapFailed,
+  onEdit,
+  onPictureFailed,
+}: {
+  pin: LatLng;
+  vendorsStubbed: boolean;
+  mapsFrameUrl: string | null;
+  /** The picture, once fetched with the SDK's bearer (lib/authed-image). */
+  staticMap: { uri: string } | null;
+  staticMapFailed: boolean;
+  onEdit: () => void;
+  onPictureFailed: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const surface = reviewMapSurface({
+    vendorsStubbed,
+    hasStaticMap: staticMap != null,
+    staticMapFailed,
+    hasFrame: mapsFrameUrl != null,
+  });
+  return (
+    <Pressable
+      onPress={onEdit}
+      accessibilityRole="button"
+      accessibilityLabel="Edit the pinned location"
+      // The picture's own clip: the card above it no longer has one, so the
+      // entrance can hang over its bottom edge.
+      style={{ borderTopLeftRadius: radius.md - 1, borderTopRightRadius: radius.md - 1, overflow: 'hidden' }}
+    >
+      {surface === 'stub' ? (
+        <AddressMapStub hasPin onLand={() => undefined} defaultCenter={pin} height={REVIEW_MAP_HEIGHT} />
+      ) : surface === 'picture' ? (
+        <View>
+          <Image
+            source={staticMap!}
+            accessibilityLabel="Map of the pinned location"
+            onError={onPictureFailed}
+            style={{ width: '100%', height: REVIEW_MAP_HEIGHT, backgroundColor: colors.backgroundSecondary }}
+            resizeMode="cover"
+          />
+          {/* The SDK's own pin, centred on the picture, so the flow shows one
+              pin throughout rather than a vendor marker on the last screen. */}
+          <View
+            pointerEvents="none"
+            style={{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0, alignItems: 'center', justifyContent: 'center' }}
+          >
+            <MapPinMarker lifted={false} color={colors.primary} />
+          </View>
+        </View>
+      ) : surface === 'pending' ? (
+        <View style={{ height: REVIEW_MAP_HEIGHT, backgroundColor: colors.backgroundSecondary }} />
+      ) : surface === 'framed' ? (
+        // The SAME framed map the pin step draws, so the applicant confirms on
+        // the imagery they placed the pin over. Touches are swallowed: the
+        // pane above it is the way back to editing.
+        <View pointerEvents="none">
+          <FramedMapPicker
+            frameUrl={mapsFrameUrl!}
+            value={pin}
+            onChange={() => undefined}
+            defaultCenter={pin}
+            defaultZoom={16}
+            height={REVIEW_MAP_HEIGHT}
+            cornerRadius={0}
+          />
+        </View>
+      ) : (
+        <MapPinPicker
+          value={pin}
+          onChange={() => undefined}
+          defaultCenter={pin}
+          defaultZoom={16}
+          pinZoom={16}
+          height={REVIEW_MAP_HEIGHT}
+          interactive={false}
+          cornerRadius={0}
+        />
+      )}
+    </Pressable>
+  );
+}

package/src/screens/address/SearchResults.tsx

@@ -0,0 +1,105 @@
+import React from 'react';
+import { Pressable, View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { Icon } from '../../components/Icon';
+import { MyazaText } from '../../components/Typography';
+import type { AddressSearchHit, PlaceSuggestion } from '../../services/api';
+
+/**
+ * The candidate list for either backend.
+ *
+ * A FAILED call renders the same empty state as no matches: there is no
+ * separate error state here, because either way the answer is the same, and
+ * the two escapes below the list are how the applicant takes it.
+ */
+export function SearchResults({
+  autocomplete,
+  suggestions,
+  hits,
+  busy,
+  onPickSuggestion,
+  onPickHit,
+}: {
+  autocomplete: boolean;
+  /** Places suggestions; null before anything has been asked. */
+  suggestions: PlaceSuggestion[] | null;
+  /** Basic-search hits; null before a submit. */
+  hits: AddressSearchHit[] | null;
+  busy: boolean;
+  onPickSuggestion: (s: PlaceSuggestion) => void;
+  onPickHit: (hit: AddressSearchHit) => void;
+}): React.ReactElement | null {
+  const { colors } = useTheme();
+  const rows = autocomplete ? suggestions : hits;
+  if (rows === null) return null;
+
+  const frame = {
+    marginTop: spacing.sm,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: radius.md,
+    overflow: 'hidden' as const,
+  };
+
+  if (rows.length === 0) {
+    return (
+      <View style={frame}>
+        <MyazaText
+          variant="bodyMedium"
+          color={colors.textSecondary}
+          style={{ paddingHorizontal: spacing.md, paddingVertical: spacing.sm + 2 }}
+        >
+          {autocomplete
+            ? 'No matches. Use your location or place the pin by hand.'
+            : 'No matches. Drag the map to place the pin instead.'}
+        </MyazaText>
+      </View>
+    );
+  }
+
+  return (
+    <View style={frame}>
+      {rows.map((row, i) => {
+        const isSuggestion = 'placeId' in row;
+        const primary = isSuggestion ? row.mainText : row.label;
+        const secondary = isSuggestion ? row.secondaryText : null;
+        return (
+          <Pressable
+            key={isSuggestion ? row.placeId : `${row.lat},${row.lng},${i}`}
+            disabled={busy}
+            onPress={() => (isSuggestion ? onPickSuggestion(row) : onPickHit(row))}
+            accessibilityRole="button"
+            accessibilityLabel={primary}
+            style={({ pressed }) => ({
+              flexDirection: 'row',
+              alignItems: 'flex-start',
+              gap: spacing.sm,
+              paddingHorizontal: spacing.md,
+              paddingVertical: spacing.sm + 2,
+              opacity: busy ? 0.6 : 1,
+              backgroundColor: pressed ? colors.backgroundSecondary : 'transparent',
+              borderTopWidth: i === 0 ? 0 : 1,
+              borderTopColor: colors.border,
+            })}
+          >
+            <View style={{ paddingTop: 2 }}>
+              <Icon name="map-pin" size={15} color={colors.primary} />
+            </View>
+            <View style={{ flex: 1, minWidth: 0 }}>
+              <MyazaText variant="bodyMedium" style={{ fontWeight: '500' }}>
+                {primary}
+              </MyazaText>
+              {secondary ? (
+                <MyazaText variant="bodySmall" color={colors.textSecondary}>
+                  {secondary}
+                </MyazaText>
+              ) : null}
+            </View>
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}

package/src/screens/address/SearchScreen.tsx

@@ -0,0 +1,176 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Pressable, View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useKycStore, useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { uuid } from '../../utils/uuid';
+import { AUTOCOMPLETE_DEBOUNCE_MS, SEARCH_MIN_QUERY_LENGTH } from '../../lib/address-flow';
+import { AddressSearchField } from './AddressSearchField';
+import { CurrentLocationRow } from './CurrentLocationRow';
+import { SearchResults } from './SearchResults';
+import type { AddressSearchHit, PlaceSuggestion } from '../../services/api';
+
+// ---------------------------------------------------------------------------
+// Screen 1: find the address the way a person holds it, as words.
+//
+// Places autocomplete when the platform has it (as-you-type, debounced, ONE
+// session token per typing session — the billing unit), the explicit-submit
+// basic search otherwise, and two always-present escapes: current location and
+// "place a pin instead". Every path lands on the pin screen.
+//
+// A failed call renders the SAME empty state as no matches: there is no
+// separate error state on this list, because either way the answer is to use
+// one of the escapes.
+// ---------------------------------------------------------------------------
+
+/** What either backend hands back once resolved to coordinates. */
+export interface ResolvedSearch {
+  lat: number;
+  lng: number;
+  houseNumber: string | null;
+  road: string | null;
+  formatted?: string | null;
+  area?: string | null;
+  city?: string | null;
+  state?: string | null;
+  postcode?: string | null;
+  /** ISO-2 of the picked address's own country (the declaration follows it). */
+  country?: string | null;
+}
+
+export function SearchScreen({
+  country,
+  autocomplete,
+  near,
+  locationHint,
+  locating,
+  onResolved,
+  onUseMyLocation,
+  onPinInstead,
+}: {
+  country?: string | null;
+  /** Which backend the server offers. */
+  autocomplete: boolean;
+  /** The device fix: a ranking bias so nearby streets come first. */
+  near?: { lat: number; lng: number } | null;
+  /** The device's resolved current address, shown ON the row. */
+  locationHint: string | null;
+  locating: boolean;
+  onResolved: (hit: ResolvedSearch) => void;
+  onUseMyLocation: () => void;
+  onPinInstead: () => void;
+}): React.ReactElement {
+  const store = useKycStore();
+  const { colors } = useTheme();
+  const [query, setQuery] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [suggestions, setSuggestions] = useState<PlaceSuggestion[] | null>(null);
+  const [hits, setHits] = useState<AddressSearchHit[] | null>(null);
+  const session = useRef(uuid());
+  const debounce = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!autocomplete) return undefined;
+    if (debounce.current) clearTimeout(debounce.current);
+    const q = query.trim();
+    if (q.length < SEARCH_MIN_QUERY_LENGTH) {
+      setSuggestions(null);
+      return undefined;
+    }
+    debounce.current = setTimeout(() => {
+      void store
+        .getState()
+        .api.addressAutocomplete(q, session.current, country ?? undefined, near ?? null)
+        .then((res) => setSuggestions(res.suggestions))
+        .catch(() => setSuggestions([]));
+    }, AUTOCOMPLETE_DEBOUNCE_MS);
+    return () => {
+      if (debounce.current) clearTimeout(debounce.current);
+    };
+    // The fix is read by value: a fresh object with the same coordinates must
+    // not re-run the search.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [query, autocomplete, country, store, near?.lat, near?.lng]);
+
+  const pickSuggestion = useCallback(
+    async (s: PlaceSuggestion) => {
+      setBusy(true);
+      try {
+        const { place } = await store.getState().api.addressPlace(s.placeId, session.current);
+        // A details call CLOSES the Places session, so the next keystroke must
+        // start a new one or the billing unit silently spans two searches.
+        session.current = uuid();
+        onResolved(place);
+      } catch {
+        setSuggestions([]);
+      } finally {
+        setBusy(false);
+      }
+    },
+    [onResolved, store],
+  );
+
+  /** The basic backend forbids autocomplete, so the query only goes out on an
+   *  explicit submit — the budget belongs to the query the person meant. */
+  const runBasicSearch = useCallback(async () => {
+    const q = query.trim();
+    if (q.length < SEARCH_MIN_QUERY_LENGTH || busy) return;
+    setBusy(true);
+    try {
+      const res = await store.getState().api.addressSearch(q, country ?? undefined);
+      setHits(res.results);
+    } catch {
+      setHits([]);
+    } finally {
+      setBusy(false);
+    }
+  }, [busy, country, query, store]);
+
+  const canSubmit = query.trim().length >= SEARCH_MIN_QUERY_LENGTH && !busy;
+
+  return (
+    <View>
+      <AddressSearchField
+        value={query}
+        onChangeText={setQuery}
+        busy={busy}
+        showSubmit={!autocomplete}
+        canSubmit={canSubmit}
+        autoFocus={autocomplete}
+        onSubmit={() => void runBasicSearch()}
+      />
+
+      <SearchResults
+        autocomplete={autocomplete}
+        suggestions={suggestions}
+        hits={hits}
+        busy={busy}
+        onPickSuggestion={(s) => void pickSuggestion(s)}
+        onPickHit={(hit) => {
+          setQuery('');
+          setHits(null);
+          onResolved({ ...hit, formatted: hit.label });
+        }}
+      />
+
+      <View style={{ height: spacing.md }} />
+      <CurrentLocationRow hint={locationHint} locating={locating} onPress={onUseMyLocation} />
+
+      <View style={{ height: spacing.md }} />
+      <Pressable
+        onPress={onPinInstead}
+        accessibilityRole="button"
+        style={{ alignItems: 'center', paddingVertical: spacing.sm }}
+      >
+        <MyazaText
+          variant="bodyMedium"
+          color={colors.textSecondary}
+          style={{ textDecorationLine: 'underline' }}
+        >
+          Place a pin on the map instead
+        </MyazaText>
+      </Pressable>
+    </View>
+  );
+}

package/src/screens/address/SkipForNow.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { Pressable } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+
+/**
+ * The address flow's escape, on the search / pin / review steps.
+ *
+ * It leaves the WHOLE flow, not just the step: a person who does not want to
+ * give an address should not be walked through the remaining three screens to
+ * decline three more times. The entrance step has no skip link of its own — it
+ * carries its own escapes instead.
+ *
+ * Hidden entirely when the workflow requires a pin.
+ */
+export function SkipForNow({
+  requirePin,
+  onPress,
+}: {
+  requirePin: boolean | undefined;
+  onPress: () => void;
+}): React.ReactElement | null {
+  const { colors } = useTheme();
+  if (requirePin === true) return null;
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel="Skip for now"
+      style={{ alignItems: 'center', marginTop: spacing.md, paddingVertical: spacing.sm }}
+    >
+      <MyazaText
+        variant="bodyMedium"
+        color={colors.textSecondary}
+        style={{ textDecorationLine: 'underline' }}
+      >
+        Skip for now
+      </MyazaText>
+    </Pressable>
+  );
+}

package/src/screens/address/StreetViewChrome.tsx

@@ -0,0 +1,81 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { MyazaText } from '../../components/Typography';
+
+// The framing chrome over the Street View panorama: a dimmed surround, a
+// white rounded frame and the caption above it. A mirror of the web SDK's
+// framer overlay (identical geometry, so hosted, embedded and native
+// applicants meet the same instrument) and the Flutter street_view_chrome.
+// RN has no box-shadow spread, so the dim mask is four views around the
+// frame. pointerEvents="none" throughout: the drag reaches the WebView.
+
+export interface FrameRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** The frame's rectangle inside a viewport: 58% wide (max 320), 56% tall
+ *  (max 300), centred horizontally, its centre 44% down. */
+export function streetViewFrameRect(viewportWidth: number, viewportHeight: number): FrameRect {
+  const width = Math.min(viewportWidth * 0.58, 320);
+  const height = Math.min(viewportHeight * 0.56, 300);
+  return {
+    left: (viewportWidth - width) / 2,
+    top: viewportHeight * 0.44 - height / 2,
+    width,
+    height,
+  };
+}
+
+const DIM = 'rgba(0, 0, 0, 0.45)';
+
+export function StreetViewChrome({
+  viewportWidth,
+  viewportHeight,
+}: {
+  viewportWidth: number;
+  viewportHeight: number;
+}): React.ReactElement | null {
+  if (viewportWidth <= 0 || viewportHeight <= 0) return null;
+  const f = streetViewFrameRect(viewportWidth, viewportHeight);
+  const right = viewportWidth - f.left - f.width;
+  const bottom = viewportHeight - f.top - f.height;
+  return (
+    <View pointerEvents="none" style={{ position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 }}>
+      <View style={{ position: 'absolute', top: 0, left: 0, right: 0, height: f.top, backgroundColor: DIM }} />
+      <View style={{ position: 'absolute', bottom: 0, left: 0, right: 0, height: bottom, backgroundColor: DIM }} />
+      <View style={{ position: 'absolute', top: f.top, left: 0, width: f.left, height: f.height, backgroundColor: DIM }} />
+      <View style={{ position: 'absolute', top: f.top, right: 0, width: right, height: f.height, backgroundColor: DIM }} />
+      <View
+        style={{
+          position: 'absolute',
+          top: f.top,
+          left: f.left,
+          width: f.width,
+          height: f.height,
+          borderRadius: 16,
+          borderWidth: 2,
+          borderColor: 'rgba(255, 255, 255, 0.95)',
+        }}
+      />
+      <View
+        style={{
+          position: 'absolute',
+          top: f.top - 40,
+          left: 0,
+          right: 0,
+          alignItems: 'center',
+        }}
+      >
+        <View style={{ borderRadius: 999, backgroundColor: 'rgba(0, 0, 0, 0.65)', paddingHorizontal: 12, paddingVertical: 6 }}>
+          <MyazaText variant="bodySmall" color="#ffffff" style={{ fontWeight: '600' }}>
+            Fit your entrance in the frame
+          </MyazaText>
+        </View>
+      </View>
+    </View>
+  );
+}

package/src/screens/address/detail-values.ts

@@ -0,0 +1,22 @@
+import type { AddressState } from '../../store/state';
+import type { DetailValues } from './DetailsSheetFields';
+
+/**
+ * The details-sheet values of an address, in the sheet's own shape: the
+ * property fields as '' when absent, the area fields as undefined when never
+ * touched (so the map's prefill shows) and '' when deliberately cleared.
+ * Shared by the pin step (sheet + summary row) so the two never disagree.
+ */
+export function detailValuesOf(address: AddressState | null | undefined): DetailValues {
+  return {
+    propertyNumber: address?.propertyNumber ?? '',
+    street: address?.street,
+    unit: address?.unit,
+    propertyName: address?.propertyName ?? '',
+    directions: address?.directions ?? '',
+    neighbourhood: address?.neighbourhood,
+    city: address?.city,
+    state: address?.state,
+    postcode: address?.postcode,
+  };
+}

package/src/screens/address/fix-source.ts

@@ -0,0 +1,27 @@
+import { precisePositionOutcome } from '../../services/location';
+import { addressVendorsStubbed, SAMPLE_ADDRESS_LINE } from '../../lib/address-flow';
+import type { FixSource } from '../../lib/address-current-location';
+import type { KycStore } from '../../store/state';
+
+// ---------------------------------------------------------------------------
+// What the current-location cache needs from the flow: the GPS reader and the
+// reverse geocoder. SANDBOX stubs BOTH (the web SDK's vendor-stub rule): a
+// canned fix with no permission prompt, and the sample label with no geocoder
+// call — the server's sandbox verdicts are canned anyway. Split from
+// use-pin-actions.ts (200-line rule).
+// ---------------------------------------------------------------------------
+
+export function fixSourceFor(store: KycStore): FixSource {
+  const stubbed = (): boolean =>
+    addressVendorsStubbed({ environment: store.getState().serverConfig.environment });
+  return {
+    takeFix: () =>
+      stubbed()
+        ? Promise.resolve({ fix: { lat: 6.4281, lng: 3.4219, accuracy: 15 } })
+        : precisePositionOutcome(),
+    addressReverse: (lat: number, lng: number) =>
+      stubbed()
+        ? Promise.resolve({ line: SAMPLE_ADDRESS_LINE, parts: null })
+        : store.getState().api.addressReverse(lat, lng),
+  };
+}

package/src/screens/address/index.ts

@@ -0,0 +1,8 @@
+// The address flow's public surface, so the step router and the header meta
+// import one path rather than five.
+
+export { AddressSearchStep } from './AddressSearchStep';
+export { AddressPinStep } from './AddressPinStep';
+export { AddressEntranceStep } from './AddressEntranceStep';
+export { AddressReviewStep } from './AddressReviewStep';
+export { addressStepMeta } from './meta';

package/src/screens/address/meta.ts

@@ -0,0 +1,44 @@
+import type { KYCStep } from '../../types/config';
+
+// ---------------------------------------------------------------------------
+// The sheet header's title and description for each address step.
+//
+// The address screens do not draw their own headers — the sheet does, from
+// here — so this is where their copy lives, beside the screens it describes.
+// KYB says "premises" where the individual flow says "your building": the pin
+// is the company's registered place of work, not somebody's home.
+// ---------------------------------------------------------------------------
+
+export function addressStepMeta(
+  step: KYCStep,
+  isBusiness: boolean,
+  /** The entrance step is framing street imagery, which describes THAT, not a camera. */
+  opts: { framing?: boolean } = {},
+): { title: string; description: string } {
+  switch (step) {
+    case 'address-search':
+      return {
+        title: 'Find your address',
+        description: 'Search it, use your current location, or place a pin on the map.',
+      };
+    case 'address-entrance':
+      return {
+        title: 'Show the entrance',
+        description: opts.framing
+          ? 'Frame your entrance in the street imagery. No camera needed.'
+          : 'A picture of the gate or front door makes the address findable.',
+      };
+    case 'address-review':
+      return {
+        title: isBusiness ? 'Confirm the premises' : 'Confirm your address',
+        description: 'Check everything is right before you continue.',
+      };
+    case 'address-collection':
+    default:
+      return {
+        title: isBusiness ? 'Is the pin on the premises?' : 'Is the pin on your building?',
+        description:
+          'Drag the map until the pin sits exactly on it. You can add details for whoever needs to find it.',
+      };
+  }
+}