@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/steps/HumanBasicInfoStep.tsx

@@ -0,0 +1,274 @@
+/**
+ * HUMAN_BASIC_INFO step — natural-person identification data.
+ *
+ *   - Form: first_name, last_name, identification_type (select from
+ *     stepConfig.accepted_country_documents), identification_id.
+ *   - Names are NFC-normalized (`normalizePersonNameSegment`) before submit.
+ *   - On submit failure: surface a `<RetryDialog>` so the user can retry
+ *     without losing their inputs.
+ *
+ * The orchestrator's view bridge (`StepUiHandle.setNode`) is how this module
+ * mounts its UI into `<VelionOnboardingScreen>`. Loading and retry overlays
+ * live alongside the form via the orchestrator's `setLoading` and the
+ * step-local retry dialog node.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { View } from 'react-native';
+import {
+  SdkErrorCode,
+  type HumanBasicInfoPayload,
+  type HumanBasicInfoStepConfig,
+  type SdkError,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { Input } from '../ui/primitives/Input';
+import { Select, type SelectOption } from '../ui/primitives/Select';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { useInlineValidation, required } from '../ui/forms';
+import { getStrings, type StringsTable } from '../i18n';
+import { resolveDocumentTypeOptions } from '../utils/documentTypeOptions';
+import { resolveDocumentOptionsFromStepConfig } from '../utils/stepConfig';
+import { normalizePersonNameSegment } from '../utils/personNameNormalize';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+
+interface FormState {
+  first_name: string;
+  last_name: string;
+  identification_type: string;
+  identification_id: string;
+}
+
+export class HumanBasicInfoStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(
+        <HumanBasicInfoView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          stepConfig={this.deps.stepConfig as HumanBasicInfoStepConfig | undefined}
+          onComplete={() => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.resolveStep();
+          }}
+          onCancel={(err) => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  stepConfig: HumanBasicInfoStepConfig | undefined;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+function HumanBasicInfoView({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const documentOptions = useMemo<SelectOption[]>(() => {
+    const fromConfig = resolveDocumentOptionsFromStepConfig(stepConfig);
+    if (fromConfig && fromConfig.length > 0) return fromConfig;
+    return resolveDocumentTypeOptions(locale);
+  }, [stepConfig, locale]);
+
+  const [form, setForm] = useState<FormState>(() => ({
+    first_name: '',
+    last_name: '',
+    identification_type: documentOptions[0]?.value ?? '',
+    identification_id: '',
+  }));
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  // Default the select to the first option once it becomes available, so the
+  // payload always has a non-empty `identification_type` even if the user
+  // submits without touching the dropdown.
+  useEffect(() => {
+    if (!form.identification_type && documentOptions[0]) {
+      setForm((f) => ({ ...f, identification_type: documentOptions[0]!.value }));
+    }
+  }, [documentOptions, form.identification_type]);
+
+  const setField = useCallback(
+    <K extends keyof FormState>(key: K, value: FormState[K]) => {
+      setForm((f) => ({ ...f, [key]: value }));
+    },
+    [],
+  );
+
+  const validation = useInlineValidation<keyof FormState>(
+    [
+      { name: 'first_name', validate: required(t.human_basic_info.nameRequired) },
+      { name: 'last_name', validate: required(t.human_basic_info.nameRequired) },
+      { name: 'identification_type', validate: required(t.human_basic_info.idTypeRequired) },
+      { name: 'identification_id', validate: required(t.human_basic_info.idNumberRequired) },
+    ],
+    (name, value) => setField(name, value),
+  );
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    if (!validation.validateAll(form)) {
+      return;
+    }
+    const first_name = normalizePersonNameSegment(form.first_name);
+    const last_name = normalizePersonNameSegment(form.last_name);
+    if (!first_name || !last_name) {
+      setBannerError(t.human_basic_info.nameRequired);
+      return;
+    }
+
+    const payload: HumanBasicInfoPayload = {
+      first_name,
+      last_name,
+      identification_type: form.identification_type.trim(),
+      identification_id: form.identification_id.trim(),
+    };
+
+    setSubmitting(true);
+    try {
+      await api.post(`/sessions/${sessionId}/basic-info/human`, payload);
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSdkError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [api, form, onComplete, sessionId, t, validation]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.common.submissionTitle}
+        message={retry.message || t.common.submissionFallback}
+        retryLabel={t.common.retry}
+        cancelLabel={t.common.cancel}
+        onRetry={() => setRetry(null)}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({
+            code: SdkErrorCode.API_ERROR,
+            message: retry.message,
+          });
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.human_basic_info.title}
+        subtitle={t.human_basic_info.subtitle}
+        iconNode={<StepIcon name="badge" />}
+      >
+        <Input
+          label={t.human_basic_info.givenNames}
+          required
+          autoCapitalize="words"
+          autoComplete="name-given"
+          textContentType="givenName"
+          autoCorrect={false}
+          value={form.first_name}
+          {...validation.bind('first_name', form.first_name)}
+        />
+        <Input
+          label={t.human_basic_info.familyNames}
+          required
+          autoCapitalize="words"
+          autoComplete="name-family"
+          textContentType="familyName"
+          autoCorrect={false}
+          value={form.last_name}
+          {...validation.bind('last_name', form.last_name)}
+        />
+        <Select
+          label={t.human_basic_info.idType}
+          required
+          options={documentOptions}
+          value={form.identification_type || null}
+          onChange={(v) => {
+            setField('identification_type', v);
+            validation.setFieldError('identification_type', null);
+          }}
+          errorMessage={validation.errors.identification_type ?? null}
+        />
+        <Input
+          label={t.human_basic_info.idNumber}
+          required
+          keyboardType="default"
+          autoCapitalize="characters"
+          autoCorrect={false}
+          value={form.identification_id}
+          {...validation.bind('identification_id', form.identification_id)}
+        />
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <Button
+          label={t.common.continue}
+          onPress={handleSubmit}
+          loading={submitting}
+          disabled={submitting}
+        />
+      </StepShell>
+      {submitting ? <LoadingOverlay message={t.common.submitting} /> : null}
+    </View>
+  );
+}
+
+function toSdkError(err: unknown, t: StringsTable): SdkError {
+  if (
+    err != null &&
+    typeof err === 'object' &&
+    'code' in err &&
+    typeof (err as SdkError).code === 'string' &&
+    'message' in err &&
+    typeof (err as SdkError).message === 'string'
+  ) {
+    return err as SdkError;
+  }
+  const message =
+    err instanceof Error ? err.message : t.common.submissionFallback;
+  return {
+    code: SdkErrorCode.API_ERROR,
+    message: message || t.common.submissionFallback,
+    cause: err,
+  };
+}

package/src/steps/HumanExtendedInfoStep.tsx

@@ -0,0 +1,353 @@
+/**
+ * HUMAN_EXTENDED_INFO — POST /sessions/:id/extended-info/human.
+ *
+ * Mirrors `HumanExtendedInfoModule.ts`. Each field's visibility and required
+ * state is read from `stepConfig.fields.<field>.{visible,required}`. Values
+ * default to `visible: true, required: true` when undefined (web parity).
+ *
+ * `gender` and `civil_status` options come from
+ * `stepConfig.fields.<field>.options` first, then `stepConfig.gender_options`
+ * / `civil_status_options` as a fallback. `birth_country` / `citizenship` /
+ * `residence_country` are 2-letter ISO codes resolved through `<CountrySelect>`.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+import { View } from 'react-native';
+import {
+  SdkErrorCode,
+  type HumanExtendedInfoPayload,
+  type HumanExtendedInfoStepConfig,
+  type SdkError,
+  type StepFieldOption,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { Select, type SelectOption } from '../ui/primitives/Select';
+import { DatePicker } from '../ui/primitives/DatePicker';
+import { CountrySelect } from '../ui/primitives/CountrySelect';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { getStrings } from '../i18n';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+import { toSubmissionError } from './_shared';
+
+export class HumanExtendedInfoStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(
+        <HumanExtendedInfoView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          stepConfig={
+            this.deps.stepConfig as HumanExtendedInfoStepConfig | undefined
+          }
+          onComplete={() => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.resolveStep();
+          }}
+          onCancel={(err) => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+function resolveSelectOptions(
+  fromField: StepFieldOption[] | undefined,
+  fromTopLevel: StepFieldOption[] | undefined,
+): SelectOption[] {
+  const raw = Array.isArray(fromField) && fromField.length > 0 ? fromField : fromTopLevel;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((opt) => {
+      const value = typeof opt?.id === 'string' ? opt.id.trim() : '';
+      if (!value) return null;
+      const display =
+        typeof opt.display_value === 'string' ? opt.display_value.trim() : '';
+      return { value, label: display || value };
+    })
+    .filter((opt): opt is SelectOption => opt !== null);
+}
+
+interface FormState {
+  gender: string;
+  civil_status: string;
+  birth_date: string | null;
+  birth_country: string | null;
+  citizenship: string | null;
+  residence_country: string | null;
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  stepConfig: HumanExtendedInfoStepConfig | undefined;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+function HumanExtendedInfoView({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const f = stepConfig?.fields;
+  const showGender = f?.gender?.visible !== false;
+  const reqGender = f?.gender?.required !== false;
+  const showCivil = f?.civil_status?.visible !== false;
+  const reqCivil = f?.civil_status?.required !== false;
+  const showBirthDate = f?.birth_date?.visible !== false;
+  const reqBirthDate = f?.birth_date?.required !== false;
+  const showBirthCountry = f?.birth_country?.visible !== false;
+  const reqBirthCountry = f?.birth_country?.required !== false;
+  const showCitizenship = f?.citizenship?.visible !== false;
+  const reqCitizenship = f?.citizenship?.required !== false;
+  const showResidence = f?.residence_country?.visible !== false;
+  const reqResidence = f?.residence_country?.required !== false;
+
+  const genderOptions = useMemo(
+    () => resolveSelectOptions(f?.gender?.options, stepConfig?.gender_options),
+    [f?.gender?.options, stepConfig?.gender_options],
+  );
+  const civilOptions = useMemo(
+    () =>
+      resolveSelectOptions(
+        f?.civil_status?.options,
+        stepConfig?.civil_status_options,
+      ),
+    [f?.civil_status?.options, stepConfig?.civil_status_options],
+  );
+
+  const [form, setForm] = useState<FormState>({
+    gender: '',
+    civil_status: '',
+    birth_date: null,
+    birth_country: null,
+    citizenship: null,
+    residence_country: null,
+  });
+  const [errors, setErrors] = useState<Partial<Record<keyof FormState, string>>>({});
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const updateField = useCallback(
+    <K extends keyof FormState>(key: K, value: FormState[K]) => {
+      setForm((prev) => ({ ...prev, [key]: value }));
+      setErrors((prev) => {
+        if (!(key in prev)) return prev;
+        const next = { ...prev };
+        delete next[key];
+        return next;
+      });
+    },
+    [],
+  );
+
+  const validateAll = useCallback((): boolean => {
+    const next: Partial<Record<keyof FormState, string>> = {};
+    if (showGender && reqGender && !form.gender)
+      next.gender = t.human_extended_info.requiredGender;
+    if (showCivil && reqCivil && !form.civil_status)
+      next.civil_status = t.human_extended_info.requiredCivil;
+    if (showBirthDate && reqBirthDate && !form.birth_date)
+      next.birth_date = t.human_extended_info.requiredBirthDate;
+    if (showBirthCountry && reqBirthCountry && !form.birth_country)
+      next.birth_country = t.human_extended_info.requiredCountry;
+    if (showCitizenship && reqCitizenship && !form.citizenship)
+      next.citizenship = t.human_extended_info.requiredCountry;
+    if (showResidence && reqResidence && !form.residence_country)
+      next.residence_country = t.human_extended_info.requiredCountry;
+    setErrors(next);
+    return Object.keys(next).length === 0;
+  }, [
+    form,
+    reqBirthCountry,
+    reqBirthDate,
+    reqCitizenship,
+    reqCivil,
+    reqGender,
+    reqResidence,
+    showBirthCountry,
+    showBirthDate,
+    showCitizenship,
+    showCivil,
+    showGender,
+    showResidence,
+    t.human_extended_info.requiredBirthDate,
+    t.human_extended_info.requiredCivil,
+    t.human_extended_info.requiredCountry,
+    t.human_extended_info.requiredGender,
+  ]);
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    if (!validateAll()) return;
+    const payload: HumanExtendedInfoPayload = {
+      ...(showGender && form.gender && { gender: form.gender }),
+      ...(showCivil && form.civil_status && { civil_status: form.civil_status }),
+      ...(showBirthDate && form.birth_date && { birth_date: form.birth_date }),
+      ...(showBirthCountry && form.birth_country && {
+        birth_country: form.birth_country,
+      }),
+      ...(showCitizenship && form.citizenship && { citizenship: form.citizenship }),
+      ...(showResidence && form.residence_country && {
+        residence_country: form.residence_country,
+      }),
+    };
+    setSubmitting(true);
+    try {
+      await api.post(`/sessions/${sessionId}/extended-info/human`, payload);
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [
+    api,
+    form,
+    onComplete,
+    sessionId,
+    showBirthCountry,
+    showBirthDate,
+    showCitizenship,
+    showCivil,
+    showGender,
+    showResidence,
+    t,
+    validateAll,
+  ]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.common.submissionTitle}
+        message={retry.message || t.common.submissionFallback}
+        retryLabel={t.common.retry}
+        cancelLabel={t.common.cancel}
+        onRetry={() => setRetry(null)}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({ code: SdkErrorCode.API_ERROR, message: retry.message });
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.human_extended_info.title}
+        subtitle={t.human_extended_info.subtitle}
+        iconNode={<StepIcon name="person" />}
+      >
+        {showGender ? (
+          <Select
+            label={t.human_extended_info.gender}
+            required={reqGender}
+            options={genderOptions}
+            value={form.gender || null}
+            onChange={(v) => updateField('gender', v)}
+            errorMessage={errors.gender ?? null}
+          />
+        ) : null}
+        {showCivil ? (
+          <Select
+            label={t.human_extended_info.civilStatus}
+            required={reqCivil}
+            options={civilOptions}
+            value={form.civil_status || null}
+            onChange={(v) => updateField('civil_status', v)}
+            errorMessage={errors.civil_status ?? null}
+          />
+        ) : null}
+        {showBirthDate ? (
+          <DatePicker
+            label={t.human_extended_info.birthDate}
+            required={reqBirthDate}
+            value={form.birth_date}
+            onChange={(v) => updateField('birth_date', v)}
+            errorMessage={errors.birth_date ?? null}
+            monthLabels={t.months}
+            maxYear={new Date().getFullYear()}
+            minYear={1900}
+          />
+        ) : null}
+        {showBirthCountry ? (
+          <CountrySelect
+            label={t.human_extended_info.birthCountry}
+            required={reqBirthCountry}
+            value={form.birth_country}
+            onChange={(v) => updateField('birth_country', v)}
+            locale={locale}
+            placeholder={t.human_extended_info.countrySearch}
+            searchPlaceholder={t.human_extended_info.countrySearch}
+            errorMessage={errors.birth_country ?? null}
+          />
+        ) : null}
+        {showCitizenship ? (
+          <CountrySelect
+            label={t.human_extended_info.citizenship}
+            required={reqCitizenship}
+            value={form.citizenship}
+            onChange={(v) => updateField('citizenship', v)}
+            locale={locale}
+            placeholder={t.human_extended_info.countrySearch}
+            searchPlaceholder={t.human_extended_info.countrySearch}
+            errorMessage={errors.citizenship ?? null}
+          />
+        ) : null}
+        {showResidence ? (
+          <CountrySelect
+            label={t.human_extended_info.residenceCountry}
+            required={reqResidence}
+            value={form.residence_country}
+            onChange={(v) => updateField('residence_country', v)}
+            locale={locale}
+            placeholder={t.human_extended_info.countrySearch}
+            searchPlaceholder={t.human_extended_info.countrySearch}
+            errorMessage={errors.residence_country ?? null}
+          />
+        ) : null}
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <Button
+          label={t.common.continue}
+          onPress={handleSubmit}
+          loading={submitting}
+          disabled={submitting}
+        />
+      </StepShell>
+      {submitting ? <LoadingOverlay message={t.common.submitting} /> : null}
+    </View>
+  );
+}