@myazahq/kyc-sdk-react-native 2.1.0 → 2.3.0

package/src/lib/step-log.ts

@@ -0,0 +1,43 @@
+// Session step log — records each SDK step the user reaches, with a
+// timestamp, so the server can reconstruct the journey on the verification
+// timeline ("consent opened → ID type chosen → document captured → …").
+// Rides the verify submission as metadata.device.stepLog — the same free-form
+// channel the Device Intelligence fingerprint uses: no extra network calls,
+// no new endpoint, and old SDKs simply never send it. `sentAt` is stamped at
+// collect time so the server can correct client-clock skew against its own
+// receipt time. Step names only — never PII. Mirrors the web SDK's
+// lib/step-log.ts; keep the two in lockstep.
+
+export interface StepLogEntry {
+  step: string;
+  at: string;
+}
+
+export interface StepLog {
+  steps: StepLogEntry[];
+  sentAt: string;
+}
+
+const MAX_ENTRIES = 40;
+
+let entries: StepLogEntry[] = [];
+
+/** Fresh slate per session (called from the store's reset — each modal open). */
+export function resetStepLog(): void {
+  entries = [];
+}
+
+/** Records a step visit. Consecutive duplicates are collapsed; back-and-forth
+ *  navigation is kept — repeat visits are honest journey data. */
+export function recordStep(step: string): void {
+  if (entries.length >= MAX_ENTRIES) return;
+  if (entries[entries.length - 1]?.step === step) return;
+  entries.push({ step, at: new Date().toISOString() });
+}
+
+/** Snapshot attached to the verify submission. Null when nothing was recorded
+ *  so the field is simply absent. */
+export function getStepLog(): StepLog | null {
+  if (entries.length === 0) return null;
+  return { steps: [...entries], sentAt: new Date().toISOString() };
+}

package/src/lib/step-window.ts

@@ -0,0 +1,96 @@
+/**
+ * Which step circles to draw, and when to start collapsing them.
+ *
+ * A KYB flow can reach FOURTEEN steps (consent → email → phone →
+ * business-details → key-people → documents → applicant-role → country-select →
+ * id-type → document-capture → nfc → liveness → questionnaire → submitted), and
+ * an individual flow eleven. The circles are a fixed size, so they cannot shrink
+ * to fit: on a 360dp Android with 16dp padding, ten steps leave 14dp TOTAL for
+ * nine connectors, and twelve steps overflow the row outright.
+ *
+ * COLLAPSING IS A LAST RESORT. The row fits as many real circles as the measured
+ * width allows and only windows once they would stop looking like a connected
+ * chain — which is what the minimum connector length below decides. A fixed cap
+ * would collapse a 9-step flow on a large phone that had room for all of it.
+ *
+ * When it does window, two rules keep the elision honest:
+ *
+ *   • The LAST step is always shown. Without it the ellipsis hides how much is
+ *     left, which is the one thing a progress indicator exists to answer.
+ *   • The FIRST step is always shown, so the row still reads as a whole journey
+ *     rather than a fragment floating in the middle.
+ *
+ *     1 ··· 5 6 7 ··· 10
+ */
+
+/** A rendered slot: a step index, or a collapsed run of them. */
+export type StepSlot = number | 'ellipsis';
+
+/**
+ * Shortest connector that still reads as a line joining two circles rather than
+ * a stray dash. Below this the "chain" metaphor is gone and the row just looks
+ * cramped — which is the state the 10-step screenshot was already in.
+ */
+export const MIN_CONNECTOR = 10;
+
+/** Horizontal margin a connector carries on each side (matches the component). */
+const CONNECTOR_MARGIN = 6;
+
+/**
+ * Never collapse below this many circles. At 5 the pattern still reads as
+ * first · gap · current · gap · last; below it the row says nothing useful.
+ */
+const MIN_CIRCLES = 5;
+
+const clamp = (v: number, lo: number, hi: number): number => Math.min(Math.max(v, lo), hi);
+
+/**
+ * How many circles fit across `width` before they stop looking like a chain.
+ *
+ *   n·size + (n−1)·(margins + minConnector) ≤ width
+ *
+ * Returns 0 when the width is not known yet, which the caller reads as "render
+ * them all" — an un-measured first frame should not flash a collapsed row.
+ */
+export function fitStepCircles(width: number, circleSize: number): number {
+  if (!Number.isFinite(width) || width <= 0) return 0;
+  const gap = CONNECTOR_MARGIN + MIN_CONNECTOR;
+  return Math.max(1, Math.floor((width + gap) / (circleSize + gap)));
+}
+
+/**
+ * @param total       how many steps the flow has
+ * @param active      0-based index of the current step
+ * @param maxCircles  how many circles fit (from `fitStepCircles`); 0 = unknown,
+ *                    render everything
+ */
+export function windowedSteps(total: number, active: number, maxCircles = 0): StepSlot[] {
+  if (total <= 0) return [];
+  const all = Array.from({ length: total }, (_, i) => i);
+  if (maxCircles <= 0 || total <= maxCircles) return all;
+
+  // A collapsed row also pays for up to TWO ellipses, each about as wide as a
+  // circle once its padding and connectors are counted. Reserving only one
+  // between them under-counted, and the row overflowed — which is invisible
+  // until you notice every `flex: 1` connector has collapsed to zero width.
+  const budget = Math.max(MIN_CIRCLES, maxCircles - 2);
+  if (total <= budget) return all;
+
+  const first = 0;
+  const last = total - 1;
+  const current = clamp(active, first, last);
+
+  // First and last are drawn unconditionally; the rest of the budget is a
+  // window centred on the current step.
+  const windowSize = Math.max(1, budget - 2);
+  const half = Math.floor((windowSize - 1) / 2);
+  const start = clamp(current - half, first + 1, Math.max(first + 1, last - windowSize));
+  const end = Math.min(start + windowSize - 1, last - 1);
+
+  const slots: StepSlot[] = [first];
+  if (start > first + 1) slots.push('ellipsis');
+  for (let i = start; i <= end; i += 1) slots.push(i);
+  if (end < last - 1) slots.push('ellipsis');
+  slots.push(last);
+  return slots;
+}

package/src/liveness/useLiveness.ts

@@ -562,7 +562,7 @@ export function useLiveness(opts: UseLivenessOptions = {}): UseLivenessReturn {
     setState((s) => ({
       ...s,
       phase: 'complete',
-      instruction: 'Verification complete',
+      instruction: 'Capture complete',
       activeChallenge: null,
       positionGuidance: null,
     }));

package/src/screens/ApplicantRoleStep.tsx

@@ -13,6 +13,7 @@ import { CountryFlag } from '../components/CountryFlag';
 import {
   KEY_PERSON_ROLE_LABELS,
   KEY_PERSON_ROLES,
+  initialsOf,
   isKeyPersonRowValid,
   namesLooselyMatch,
 } from '../config/keyPeople';
@@ -43,16 +44,6 @@ const APPLICANT_ROLE_LABELS: Record<ApplicantRole, string> = {
   authorized_representative: 'Authorized representative',
 };
 
-/** "Richard Ingwe" → "RI" — the avatar monogram. */
-function initialsOf(name: string): string {
-  return name
-    .trim()
-    .split(/\s+/)
-    .slice(0, 2)
-    .map((t) => t[0]?.toUpperCase() ?? '')
-    .join('');
-}
-
 export function ApplicantRoleStep(): React.ReactElement {
   const store = useKycStore();
   const config = useKycConfig();

package/src/screens/BusinessKeyPeopleStep.tsx

@@ -1,15 +1,17 @@
-import React from 'react';
+import React, { useState } 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 { BusinessKeyPersonRow } from './BusinessKeyPersonRow';
+import { KeyPersonCard } from './KeyPersonCard';
+import { KeyPersonSheet } from './KeyPersonSheet';
 import { keyPeopleMinEntries } from '../config/businessSteps';
 import {
   emptyKeyPerson,
   invalidKeyPersonRows,
+  isKeyPersonRowBlank,
   isKeyPersonRowValid,
   MAX_KEY_PEOPLE_ROWS,
   type KeyPersonEntry,
@@ -24,9 +26,10 @@ import type { KeyPersonRole } from '../types/business';
 // `undisclosed`, which is a risk signal in its own right. So this screen is not
 // merely data entry — what the applicant chooses to omit is evidence.
 //
-// Layout, copy and per-row design mirror the web SDK's BusinessKeyPeopleStep
-// (and Flutter's screen) 1:1 — the description lives in the step HEADER, the
-// hints are dashed cards, and each person is a bordered card with selects.
+// The list stays a clean stack of compact summary cards; the FORM lives in the
+// add/edit sheet (KeyPersonSheet). Tapping a card edits it; "Add a person"
+// opens a fresh sheet. Removal is inside the edit sheet, behind a deliberate
+// tap — never one stray touch on the list.
 // ---------------------------------------------------------------------------
 
 export const businessKeyPeopleMeta = {
@@ -35,45 +38,62 @@ export const businessKeyPeopleMeta = {
     "List the company's directors and owners of 25% or more. Each will receive a link to verify their identity.",
 };
 
+type SheetState = { mode: 'add' } | { mode: 'edit'; index: number } | null;
+
 export function BusinessKeyPeopleStep(): React.ReactElement {
   const config = useKycConfig();
   const store = useKycStore();
   const { colors } = useTheme();
   const rows = useKyc((s) => s.businessApplication.keyPeople);
   const registryCountry = useKyc((s) => s.business.country);
+  const [sheet, setSheet] = useState<SheetState>(null);
 
   const minEntries = keyPeopleMinEntries(config.business);
   const validCount = rows.filter(isKeyPersonRowValid).length;
   const invalidRows = invalidKeyPersonRows(rows);
+  const uboThreshold = config.business?.keyPeople?.ownershipThreshold ?? 25;
 
   // Combined ownership above 100% is factually impossible — catch the typo
   // here rather than shipping it into the registry cross-check as a doomed
   // mismatch. Under 100% is fine (not every owner has to be listed).
-  const totalPct = rows.reduce((sum, row) => {
+  const pctOf = (row: KeyPersonEntry): number => {
     const n = Number(row.ownershipPct);
-    return row.ownershipPct.trim() !== '' && Number.isFinite(n) ? sum + n : sum;
-  }, 0);
+    return row.ownershipPct.trim() !== '' && Number.isFinite(n) ? n : 0;
+  };
+  const totalPct = rows.reduce((sum, row) => sum + pctOf(row), 0);
   const overAllocated = totalPct > 100;
+  const fmtPct = (n: number): string => (Number.isInteger(n) ? String(n) : n.toFixed(1));
 
   const canContinue = validCount >= minEntries && invalidRows.length === 0 && !overAllocated;
 
-  const update = (index: number, patch: Partial<KeyPersonEntry>): void => {
-    store.getState().setKeyPeople(rows.map((row, i) => (i === index ? { ...row, ...patch } : row)));
-  };
-  // New rows default to the business's registry country (picked on the
+  // New people default to the business's registry country (picked on the
   // details step) — most directors are local, and a foreign one just switches
   // theirs. Mirrors the web and Flutter SDKs.
   const defaultCountry = registryCountry ?? config.business?.country ?? '';
-  const add = (): void =>
-    store.getState().setKeyPeople([...rows, { ...emptyKeyPerson(), country: defaultCountry }]);
-  const remove = (index: number): void =>
-    store.getState().setKeyPeople(rows.filter((_, i) => i !== index));
+
+  const commit = (next: KeyPersonEntry[]): void => store.getState().setKeyPeople(next);
+  const handleSave = (entry: KeyPersonEntry): void => {
+    if (sheet?.mode === 'edit') {
+      commit(rows.map((row, i) => (i === sheet.index ? entry : row)));
+    } else {
+      commit([...rows, entry]);
+    }
+    setSheet(null);
+  };
+  const handleRemove = (): void => {
+    if (sheet?.mode === 'edit') commit(rows.filter((_, i) => i !== sheet.index));
+    setSheet(null);
+  };
+
+  // Indexed access may be undefined under strict indexing — resolved once here
+  // so the sheet only ever mounts with a real entry.
+  const editEntry = sheet?.mode === 'edit' ? rows[sheet.index] : undefined;
 
   const handleContinue = (): void => {
     if (!canContinue) return;
     // Half-typed rows are dropped rather than submitted: an entry the user
     // abandoned is not a person they disclosed.
-    store.getState().setKeyPeople(rows.filter(isKeyPersonRowValid));
+    commit(rows.filter(isKeyPersonRowValid));
     store.getState().nextStep();
   };
 
@@ -98,6 +118,7 @@ export function BusinessKeyPeopleStep(): React.ReactElement {
             borderRadius: radius.sm,
             backgroundColor: colors.backgroundSecondary,
             padding: spacing.md,
+            marginBottom: spacing.md,
           }}
         >
           <MyazaText variant="bodySmall" color={colors.textSecondary}>
@@ -105,45 +126,80 @@ export function BusinessKeyPeopleStep(): React.ReactElement {
           </MyazaText>
         </View>
       ) : null}
-      {overAllocated ? (
+
+      {rows.map((row, index) =>
+        isKeyPersonRowBlank(row) ? null : (
+          <KeyPersonCard key={index} entry={row} onPress={() => setSheet({ mode: 'edit', index })} />
+        ),
+      )}
+      {/* The cards and the add affordance are different things — give the
+          boundary some air (cards already carry a small bottom margin). */}
+      {rows.some((row) => !isKeyPersonRowBlank(row)) ? (
+        <View style={{ height: spacing.sm }} />
+      ) : null}
+
+      {rows.length < MAX_KEY_PEOPLE_ROWS ? (
+        <MyazaButton
+          label="Add a person"
+          variant="outline"
+          leadingIcon="user-plus"
+          onPress={() => setSheet({ mode: 'add' })}
+        />
+      ) : (
+        <MyazaText variant="bodySmall" color={colors.textMuted} style={{ textAlign: 'center' }}>
+          {`You can list up to ${MAX_KEY_PEOPLE_ROWS} people here.`}
+        </MyazaText>
+      )}
+      {/* Breathing room between the add-person affordance and the summary bar —
+          matches the Flutter screen's SizedBox after its outline button. */}
+      <View style={{ height: spacing.md }} />
+
+      {/* Total-ownership summary at the DECISION point — the disabled Continue
+          button always explains itself, wherever the offending card is. */}
+      {totalPct > 0 ? (
         <View
           style={{
-            borderWidth: 1,
-            borderColor: `${colors.error}4D`,
+            flexDirection: 'row',
+            justifyContent: 'space-between',
+            alignItems: 'center',
+            backgroundColor: overAllocated ? colors.errorBg : colors.backgroundSecondary,
             borderRadius: radius.sm,
-            backgroundColor: colors.errorBg,
-            padding: spacing.md,
-            marginTop: hint ? spacing.sm : 0,
+            paddingHorizontal: spacing.md,
+            paddingVertical: spacing.sm + 4,
           }}
         >
-          <MyazaText variant="bodySmall" color={colors.error}>
-            {`The ownership percentages add up to ${totalPct}% — together they can't exceed 100%.`}
+          <MyazaText variant="bodySmall" color={overAllocated ? colors.error : colors.textMuted}>
+            Total ownership listed
+          </MyazaText>
+          <MyazaText
+            variant="bodySmall"
+            color={overAllocated ? colors.error : colors.textDark}
+            style={{ fontWeight: '700' }}
+          >
+            {`${fmtPct(totalPct)}%`}
           </MyazaText>
         </View>
       ) : null}
-
-      {rows.map((row, index) => (
-        <BusinessKeyPersonRow
-          key={index}
-          row={row}
-          index={index}
-          onChange={(patch) => update(index, patch)}
-          onRemove={() => remove(index)}
-          uboThreshold={config.business?.keyPeople?.ownershipThreshold}
-        />
-      ))}
-
-      <View style={{ height: spacing.md }} />
-      {rows.length < MAX_KEY_PEOPLE_ROWS ? (
-        <MyazaButton label="Add a person" variant="outline" leadingIcon="user-plus" onPress={add} />
-      ) : (
-        <MyazaText variant="bodySmall" color={colors.textMuted} style={{ textAlign: 'center' }}>
-          {`You can list up to ${MAX_KEY_PEOPLE_ROWS} people here.`}
+      {overAllocated ? (
+        <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.xs }}>
+          {`Together the percentages can't exceed 100% — reduce them by ${fmtPct(totalPct - 100)}%.`}
         </MyazaText>
-      )}
+      ) : null}
 
-      <View style={{ height: spacing.sm }} />
+      <View style={{ height: spacing.md }} />
       <MyazaButton label="Continue" onPress={handleContinue} disabled={!canContinue} />
+
+      {sheet && (sheet.mode === 'add' || editEntry) ? (
+        <KeyPersonSheet
+          mode={sheet.mode}
+          initial={editEntry ?? { ...emptyKeyPerson(), country: defaultCountry }}
+          uboThreshold={uboThreshold}
+          otherPctTotal={editEntry ? totalPct - pctOf(editEntry) : totalPct}
+          onSave={handleSave}
+          onRemove={sheet.mode === 'edit' ? handleRemove : undefined}
+          onClose={() => setSheet(null)}
+        />
+      ) : null}
     </View>
   );
 }

package/src/screens/IdTypeStep.tsx

@@ -99,6 +99,19 @@ export function IdTypeStep(): React.ReactElement {
     return (table[country.toUpperCase()] ?? []).filter((t) => allowed(t.key));
   }, [country, config.idTypes, config.countries, serverConfig]);
 
+  // Document Intelligence off ⇒ number-only IDs only (there is no document
+  // capture step), so drop every document-scanned ID from the picker. This is
+  // what makes the disabled step actually disappear from the live flow rather
+  // than still offering passports and licences that then have nowhere to be
+  // captured. Mirrors the web SDK's IdTypeStep.
+  const visible = useMemo<IdTypeDefinition[]>(
+    () =>
+      config.enableDocumentCapture === false
+        ? available.filter((t) => !t.requiresDocumentCapture)
+        : available,
+    [available, config.enableDocumentCapture],
+  );
+
   if (serverConfig.status === 'loading') {
     return (
       <View style={{ paddingVertical: spacing.xl, alignItems: 'center' }}>
@@ -107,7 +120,7 @@ export function IdTypeStep(): React.ReactElement {
     );
   }
 
-  if (serverConfig.status === 'ready' && available.length === 0) {
+  if (serverConfig.status === 'ready' && visible.length === 0) {
     return (
       <View
         style={{
@@ -127,7 +140,7 @@ export function IdTypeStep(): React.ReactElement {
 
   return (
     <View>
-      {available.map((t) => {
+      {visible.map((t) => {
         const selected = selectedIdType === t.key;
         return (
           <Pressable

package/src/screens/KeyPersonCard.tsx

@@ -0,0 +1,119 @@
+import React from 'react';
+import { Pressable, View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { Icon } from '../components/Icon';
+import { CountryFlag } from '../components/CountryFlag';
+import {
+  KEY_PERSON_ROLE_LABELS,
+  initialsOf,
+  isKeyPersonRowValid,
+  type KeyPersonEntry,
+} from '../config/keyPeople';
+import { regionCountryName } from '../config/regions';
+
+// ---------------------------------------------------------------------------
+// One saved key person, summarised — monogram avatar with their ID-issuing
+// country flag badged on its corner, name, role · ownership meta, and the
+// email their invite will go to. The whole card opens the edit sheet (the
+// chevron is the affordance); removal lives INSIDE that sheet, so a stray tap
+// can never delete a person.
+//
+// Same visual language as the applicant step's "this is me" cards, so the two
+// screens read as one system.
+// ---------------------------------------------------------------------------
+
+export function KeyPersonCard({
+  entry,
+  onPress,
+}: {
+  entry: KeyPersonEntry;
+  onPress: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const name = entry.name.trim() || 'Unnamed person';
+  const country = entry.country.trim() ? entry.country.trim().toUpperCase() : null;
+  const pct = entry.ownershipPct.trim();
+  // A row persisted by the old inline UI (or interrupted mid-edit) may be
+  // incomplete — the card says so instead of silently blocking Continue.
+  const incomplete = !isKeyPersonRowValid(entry);
+
+  const meta = [KEY_PERSON_ROLE_LABELS[entry.role], pct ? `${pct}% ownership` : null]
+    .filter(Boolean)
+    .join(' · ');
+  // The flag alone doesn't say WHICH country — spell it out, alongside the
+  // email their invite goes to.
+  const detail = [country ? regionCountryName(country) : null, entry.email.trim() || null]
+    .filter(Boolean)
+    .join(' · ');
+
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel={`Edit ${name}`}
+      style={({ pressed }) => ({
+        flexDirection: 'row',
+        alignItems: 'center',
+        borderWidth: 1,
+        borderColor: incomplete ? colors.error : colors.border,
+        borderRadius: radius.sm,
+        backgroundColor: pressed ? colors.backgroundSecondary : colors.background,
+        padding: spacing.md - 2,
+        marginBottom: spacing.sm,
+      })}
+    >
+      <View
+        style={{
+          width: 40,
+          height: 40,
+          borderRadius: 20,
+          backgroundColor: colors.primary100,
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '700' }}>
+          {initialsOf(name)}
+        </MyazaText>
+        {country ? (
+          <View
+            style={{
+              position: 'absolute',
+              bottom: -2,
+              right: -4,
+              borderRadius: 10,
+              borderWidth: 2,
+              borderColor: colors.background,
+              overflow: 'hidden',
+            }}
+          >
+            <CountryFlag country={country} size={16} />
+          </View>
+        ) : null}
+      </View>
+
+      <View style={{ flex: 1, minWidth: 0, marginLeft: spacing.sm + 4 }}>
+        <MyazaText variant="bodyMedium" numberOfLines={1} style={{ fontWeight: '600' }}>
+          {name}
+        </MyazaText>
+        <MyazaText variant="bodySmall" color={colors.textMuted} numberOfLines={1} style={{ marginTop: 1 }}>
+          {meta}
+        </MyazaText>
+        {incomplete ? (
+          <MyazaText variant="bodySmall" color={colors.error} numberOfLines={1} style={{ marginTop: 1 }}>
+            Incomplete — tap to finish
+          </MyazaText>
+        ) : detail !== '' ? (
+          <MyazaText variant="bodySmall" color={colors.textMuted} numberOfLines={1} style={{ marginTop: 1 }}>
+            {detail}
+          </MyazaText>
+        ) : null}
+      </View>
+
+      <Icon name="pencil" size={16} color={colors.textMuted} />
+    </Pressable>
+  );
+}